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We don’t know about you, but for thttse of us at 
MacTech, (the magazine has it's offices in Los Angeles 
and Arlington, VA) it’s been hot this summer. Very hot! 
But that’s the way we like our weather, and it’s the way 
we like the marketplace we are in, the Mac technology 
market!! 

To say Apple’s been hot would be a huge 
understatement! In its fiscal 3™ Quarter, ending June 
25*^^,Apple reported the highest revenue and profit in its 
history. It’s now a $l^billion company. Apple shipped 
almost 1.2 million Macs in the quarter and over 6 million 
iPods. (Know anyone who doesn’t have one? Other than 
your parents?) It’s an exciting market again, and we 
couldn’t be more thrilled to be an integral part of it!! 

As good as Apple’s financial results are, the 
technology side of things is just as strong. We think 
Tiger is clearly the best commercial OS that has ever 
been released. The opportunities for Apple to make 
significant inroads in the Enterprise market are 
enormous. In our heart of hearts we hope Apple seizes 
on this opportunity and shouts its very strong 
Enterprise message from every mountaintop and in 
every corporate CIO’s office around the world. We 
sure are doing our part to help. No problem Steve, 
don’t mention it! © 

We have anotiter great line-up of articles and columns for 
you this month. While last month we learned Dave Mark has 
lx;come a boater, (licre’s fair warning to all you boaters, 
swimmers and Jet Skiers on Viiginiii’s beautihil Lake Anna!!) tiiis 
month Dave continues his journey into PIIP/MySQL widi a 
great Getting Started on implementing HTML forms. For those 
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of you who liavc been liaiigiiig on leave's every word in tliis 
series, yon are going to really enjoy and learn from Uiis great 
column. Dave also makes mention of a really wontierfLil new 
b(K)k from Mac legend Scott Knaster. Hie Ixnik is called 
Hacking Mac OS X Tiger: Serious Hacks, Mods and 
CustomizationsXou can find more about this wonderfriJ book, 
diat we very highly reconunend, and can even read an excerpt 
chapter at: 

http ://www. wi ley. com AV i I ey C D AAV i I eyTi tl e/p rod u etC d - 
076458345X.html 

Our featured cover .story this month is from our 
AppleScript Editor, Ben Waldie. From the feedback we received 
we know all of you have been reading Ben’s grejit AppleScript 
columns each month, lliis mondi Ben introduces us to the 
exciting world of creating Automator Actions with AppleScript. 
For anyone who is comt()rtable in AppleScript, and wants to 
learn more about Automator, this column is a must! 

In this month’s installment of Mac In The Shell, Ed 
Marezak brings us Part II of his exploration of DNS and 
E-mail. After a fine introductory piece last month on the 
basics, this month Ed shows us how to use the Terminal 
to really dig-in, isolate the sources of trouble and resolve 
issues quickly. This piece is a must for anyone who is 
administering mail services and wants to use the 
I’erminal as a primary tool to facilitate this task. 

For us, one of the best parts of attending WWDC is the 
opportunity to meet exciting new talent in the Mac 
technical community. While on the bus ride from 
Moscone to (aipertino for this year’s big Apple bash, 
Canyone else like the Wallflowers?), we met and got to 
know a consultant and writer we are excited to be 
bringing to our readers. His name is Emmanuel Stein and 
he runs a consulting company in NYC called Macverse.ln 
his debut for MacTech, Emmanuel is checking in from the 
Security Beat with a piece on using GPG to secure your 
mail. Read it and let us (and Emmanuel at 
macverse@mac.com') know what you think. In the 
coming months be looking for pieces from Emmanuel on 
demystifying the data storage alphabet soup and Open 
Source package management tools like Pink and Open 
Darwin Ports. 

We have another new contributor with us this 
month. Jose Cruz, a freelance engineering consultant 
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from British Columbia, brings us a really great, in-depth 
piece on progaming for the Palm OS on OS X.The Piece, 
Dissecting The PDH File, is a very strong exploration of 
using Cocoa, Core Foundation and XCode to build 
applications and utilities for the Palm OS. We really enjoy 
Jose’s writing and will be running more pieces from him 
in future issues of MacTech. 

After a few months away, frequent contributor Paul 
Ammann is back with us this month. Check out his really 
fine article on Exclusivity and file access in OS X, 
Exclusive File /Icces's in Mac OS X. David Hill is also 
back this month with a really enjoyable and informative 
piece on OS X’s 2D drawing API, Quartz 2D, Mineralogy 
101. Enjoy! 

After a month’s hiatus (either it’s hot in Chicago too or 
liis ten rounds with Michael Bell just wore him out!) our 
resident Open Source bigot Dean Shavit, introduces us to 
the wonderful world of Squirrel Mail and shows us how to 
get the most out of this really super open source WebMail 
package. Welcome back Source Hound! We missed ya!! 

Tim Monroe, our resident QuickTime guru, this 
month introduces us to the wonderful world of Threads 
and, more specifically, performing QuickTime operations 
of them. We really love this current series from Tim and 
we are sure you will enjoy the latest installment of the 
MacTech QuickTime Toolkit! Be reading next month 
when Tim explores all the hottest stuff introduced in 
Quick'l'ime 7! 

Jt)hn Welch brings us Part II of last month’s cover 
story on 'I'iger Server. Picking up where he left off last 
month,John focuses on Workgroup manager and all the 
tools Tiger Server provides to help us better manage 
networks, Read John’s piece to learn how to set-up 
sharepoints and access policies for those sharepoints, 
set client machines and client machine groups, their 
access policies and preferences, set users and user 
groups, their access policies and preferences and 
perform manual manipulation of Open Directory data. 

All this and we get to live in America too! What could be 
better than this? We’re hungry for your feedback. Let us 
know what you tliink at editorial@mactech.com . 

Until next month, we hope you enjoy another great issue 
of MacTech!! 
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GATING SMRTfO Dave Mark 


PHP, MySQL, 

And Forms 


I n our last PHP/MySQL exploration, we used the MySQL 
monitor to build a database, create a new table, then populate 
the table with data. We did use our PHP chops to query the 
table and spit out some HTML with the results, but that’s a pretty 
bare-bones/hard-coded approach. A more common technique is to 
use an HTML form to populate the table. For example, suppo.se you 
were building an order-entry system for your sports memorabilia 
shop. You could use the MySQL monitor to enter all the data that 
represents your inventory. If you are really comfortable with the 
monitor, that’s not a terrible approach. But, what if you want your 
assistant, who is a whiz at the web but has no MySQL experience, 
to manage the data? Creating a series of HTML-driven forms is 
definitely the way to go. 


Before we dig into ihif; month's 
sample code, Td like to take a 
momentary detour to talk about a 
terrific new ]>ook 1 just got. 

Hacking Mac OS X 
Tiger 

Back in the early days of 
Macintosh, diere were just a very few 
Mac programming titles. One of the 
best of these books was called 
Macintost Programmiptg Secrets. 
WriLLen )->y Scot! Knaster and Keith 
Rollin, the book rjuickly ix?came a cult 
classic. Well, Scott is hack and his latest 
[xx>k is every bit as cxx>l as Macintosh 
Prtjgramming Seaets. Hk" long title is 


Hacking Mac OS X Tiger: Seriims Hacks, Mods, and 
Customizations. Tills Ls no idle boast. The l>tK)k is chock 
fiill of wonderful insider info, and is just plain fun. 

The [>ook starts off with a c‘ollection of tips. For 
example, try liolding down the oj^tion key, then pressing 
the volume up (or dtwn) key on your keyboard. Cool! 
The Volume System Fref OfXfns. There are tips for the 
Finder, the Dtx:k, Dashboarcf System Frefs, iTunes, and a 
lor more. To me, Uie hcx^k is worth the price of admission 
jusi for that part along. But wait, there's more! 

Tlie second part of the Ixxjk is called Mcxls, and 
explores more developer-oriented things. Things like 
AuLomator, Xcode, Property Lists, and Application 
Bundles, Lt>Ls of great info here, c,specia!ly if you are 
reiatively new to Mac: develc:)pment. 

The tliird part of llic ijook might be my favorite. It's 
called Hacks, and is full of, well, urn, hacks! You 11 
tTjstomize dock icon behavior, hack some Da-shboard 
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widgets, even redireti yoitr web cam out pu r to create a 
Jive video desltUrp. 

All this stuff is presented in Scott Knaster's wiiiy, 
irreverent style. I totally love this lx>ok! Hacking Mac OS 
X Tiger is part of Wiley's KxtremeTecb series. You can find 
it at: 

http://vvvvw.wiiey.comAYileyCDA/WileyTitle/productC 

d^076458345X.html 

And now back to our regularly scheduled 
prt)gramming.,. 

Implementing a Form with PHP 

The key to implcincnling an HlMl, form is the 
<form> tag. Typically, the <forin> tag will include lx>th 
action and method attributes. Tlic action attribute 
specifies the name of tite fife to which to .send the fonifs 
results. I'he method attriixjte specifies how form data is 
passed along to the action recipicni and is either Gti l' or 
POST. Tile primary difference l>etween Gi^r and POST is 
that GEl c’^iuses the fonn data to be emlx-dded in the 
action's IJKi, wliile POST* passes ihe data to the action as 
an input stream (via stdin, for example). GK*r forms can 
be Ixiokmarked, sin<:e tlie data is embedded in the URL. 
POST forms cannot Ijc Ixrokmarked, 

In generah I use POST as my default unless I 
specifically need a URL to be bookmarkiilile. You've 
undoubtedly clicked on your browser's reload button 
and been asked, “Do you really want to reload this 
form?” or something similar. The page in question is a 
POST request. 

Good to know the difference Ix^tween GFf and 
POST, use whichever works l>est in any situation. Note 
that GBT is the delault. Note also that if your form 
contains passwords and the like, the GET URL will include 
liic password data. Not a great idea if you will be pas.sing 
the URL around. 

Embedded between the <form> and </forni> tags is 
the form content. The form content is made up of HTM L 
formatted text, akmg with a variety of <input> tags. 
Each <inpul> tag represents an HTML form element, 
such as a popup menu, texi field, non-echoing text field 
(for entering passwords), checkbox, radio t>Litton, 
submit fuiUtm (a pushbutton whose purpose is to 
submit the form) or a reset l)utton (a pushbutton used 
to clear the form). 

An example will make this a bit clearer. 

A PHP Form Example 

This example puts up a pair of text fields, with 
appropriate labels. One field is a standard text field, Llie 
second a non-echoing text field. We'll use the fonner to 


enter your name and the latter to enter a password. We'll 
end the form with a .siihmii l)Utton, When the submit 
button is pres.sed, the same page will be reitjaded. The 
rechni<[ue o\' taking two differeni acLions on the same 
page of FHP cxxle is a common PHP theme. While this is 
nt)i a particulariy useful example, it demonstraies tliis 
concept nicely. 

Using BBEdil, or yt>ur favorite pLain-text editor, create 
a new plain-text file and save it as php^^omiOI.php, llien 
type the following source code into the file: 

<htnil> 

<bead> 

<tltle>Saiiipie PUP Fartit</tltle) 

</hcii9d> 

<l>oc!y> 

<?php 

if ( lemptyf S.POST[ ‘napie' ! ) ) I 

echo “Your name is tS_?0STl ]|,<hr />“: 

echo “Your paf^sword is f$_POST| * ])-<l>r />“: 

I 

?> 

<foriii actlon-"<7php $FJiP_SELF: 1>" raethod="POyT"> 

Kamo; 

(input type=''text“ iiame="naiiie“ l> 

(br /> 

Password; 

(input typo^“pasfrvord" name’“pw<l“ /> 

(br /> 

(input type=“subnilt“ /> 

(/form) 

(/body) 

</litnil> 

Save the file and copy It inio tlic Sites directory in 
yc^ur htaue directory. For example, I placed my c:opy of 
this code into /Users/davemark/SitesA 

Once this is done, fire up your favorite browser and 
enter tliis URL: 

http://127.0,0. l/'“davemark/php_form01 ,php 

Be sure lo replace davemark wiili your own user 
name. Also, Ixf sure to keep the tilda (-*). 

Once you enter the URL, you should see results 
similar lo those shown in Figure U If you don't, be sure 
yt)ur PHP server is running. To do this, create a new, 
plain-text file named ieslpbp, fill it with these 3 lines 
of code: 

<?piip 

phpinfoU 

?> 


Drag the test file into your Sites direcuiry and type 
this URL into your browser: 

http://127.0,0 J/-davemarl</test.php 
Reiiieml^er to replace davemark with your user name. 
If the large PHP iMe appears in your browser, PI IP is 
running and you've got an error in your version of 
php_/ormOI.php. If the large PUP table does nol appear, 
go back to the installation instaictions For PHP and make 
sure your server is up and running. 
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Figure L The Sample PHP Foim in action. 

Click in the Name field and type your name. Next, 
tal) over Lo or click in the Piissw<trd fieltl and tyi^e a 
password. Note that the password churacLcrN echo as 
dots. I'll show you wliy in a second. 

Finally, click the Submit I mutton. You should sec 
something like the output shown in Figure 2. Notice that 
the name and password are both echoed and the Ibrtn is 
then reloaded so you can try this again. 



Figure 2. The name and password are echoed and the 
form is reloaded. 

Let's take a kK>k at the code, see lu>w ihis wc^rks* 

We Starr with the [)asic <htiTil>, <head>, <liiie>, and 
<body> tags* Nothing new there. 

<hlrnl> 

Sample PRP ForiB</tltle> 

</head> 

(body) 

llic first thing we dtj in ihe H TML Ixxly is open a FI IF 
tag and jump into an it statement. The if statement calls the 
PHP function emptyO to see if the variable $_PONll 'name" 
/ is empty, that is, see if it has been set to a value. 

Whenever you see a PHP funtaion and don't know 
what it is, make your way over to http://php.net, type the 
functiem name in the mearch for text field, select fimciion 
list from the in the popup menu, then click the arrow to 
do your search. The result of my search for the empty 
function is sliown in Figure 3. 



Figure 3. Searching for the empty function on php.net 


what the heck is $_POST[ "name* p What a weird 
name Ibr a variable. The variable $_POST is an 
associatWe array. An asstx'iative army is an array that is 
indexed by name instead of by numerical index. For 
exam|>lL% yt)u might have an array of nicknames for all 
yoLir friends, wliere Snicknamesl Tred* ] is set to the string 
■Siulihy', while $nicknamesf Phil’ ] is set to 'Scooter’. 

Nt)te that the ejuotes ate optional for single word strings. 
St> you might see $nicknamesl Fred 1, Tltougli diat will work, 
leaving out the quotes will make your code a bit more 
ayptic, so use them unless you find yoursetf in a funky 
situation wliere they just get in tlie way (<|uoted string inside 
another quoted siring, for example). And even then, be sure 
to comment yoitr ctxle so everyt>ne ciin tbllow along. 

$_POST is an associative array lhal contains an 
element for each of your form’s input fields. So $_POST( 
*na!Tie' 1 contains the contents of the input element with the 
name “name". SJKiS'll 'pwd’ 1 contains the contents of the 
input elemeiu with the name ''pwd". You get the ide^i. 

Tlie goal of the if' statement is to see if die name field Ls 
empty. If not, we’ll use echo lo display the contents of die 
name field. Want to learn alx>ut echo? Go to php.net and 
ty|x* eiiio in llie search fiekf nse.trt'h the function list. AlxiiU 
? of die way down tlie page, ytni'll see a nicx? comment 
alxjut using braces* Tliis Is wortli reading. In a nurshelf you 
om use braces as separators when a space character just 
won’t do. For example, in the emfe below, we used the 
braces to .set iilT the name $_POSn ‘name’ I without ptitting 
a space lx*twecn the end of the variable and the fxriod. Tliis 
leLs LIS put a pericxl immediately after your nLime. 

Note that we included the <br /> HTML tag in our 
output. Remember, I he tTlF eexie spits out HTML as its 
output and then the HTML is pa.ssed back to the browser. 
The <br /> Lag is used to put a rciom after the name anci 
again after the password. 

<?php 

if ( terapty( $^FOSTl 'name' 1 ) ) [ 

echo '"ifour is !$ POST! 'name' li.<bi: 

echo "Your password is |$_POST[ 'pwd' J).<br />"; 

1 

r> 
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If I lie natiic field was filled, we’ll already have printed 
the name and password liefore we get to this point. If the 
name field was empty, nothing will have been generated 
yet. Hither way, we are now going to put up tlie form. 

The <fonii> tag takes an action attribute and a 
method. We already knt)w about the inediod. The action 
is the file you want served up witli the results of your 
action. We could have created a sectjnd page that 
displayed tiie results of our form. But this seif-referential 
approach is pretty c:oinmon in FUR We used the variable 
$FHP_SHl.F to liave the form pass the results on to the 
same file, sort of like a funaion calling itself. Want to learn 
more alxiut $PHP_SEI.F? It's not a hinction, so well need 
to search the whole site instead of just the function list. 
When you search all of php.nct. you’ll get a Google list of 
pages to look at. Here’s a good place to start: 

httpy/us3. php.net/reserved. variables 

You1l need to search the page for PPrP_SELH'. Note 
that the $ is not part of Uie variable name. 

<forDi action"'’<7php $t'liF_SEtFi metPOST"> 

The tw'o <input> tags specify a text field and a 

password field, lioth do the same tiling, but the password 
field echoes input as dots instead of the actual characters. 
Note that the name attributes of each <lnpin> tag arc what 
link the resulLs to the $_FOS'l' a.ssociaie array index. 

Giput type”"text" name'*"name" 

<Ur /> 

Password: 

Clnput password" natae-"pwd" /) 

<br /> 

Finally, Uie last bit of <inpuf> for the fonn is the 
sutiinii button. 

<input /> 

< / ft) riiV 

</body> 

Type your natne and pa-ssword again and again. Each 
lime you click submit, the page reloads, draws your name 
and pa.ssworcl, and then redraw.s the blank form. Ccxil! 

Adding MySQL to the Picture 

Our next step is to add MySQL to the picture. We’l! 
build a dutaljase, using the MySQL monitor, create a new 
table, then use the form we created to populate ihe 
database. If you are new to the MySQL mt)nitor, go back 
June*s Geliing Started cotumn for a review. 

Fire up Terminal and start die MySQL monitor. As a 
reminder, 1 set up an alias for mysql: 

alias mysql^'/usr/loca1/nysql/bin/mysql' 

Here's my set|uencc for starting MySQL, building the 
cLjtaha,se, and l:»uilding the table: 


Daves’Computer:- davejiiark$ roysql -u root 'p 
Enter password : 

Weloone to the HySQL nfonitot. end with ; or 

Your MySaL connection id is 16 to server version: 4.1.12- 
standard 

Type Vhelp:" or "\h* for help. Type *\c‘ to clear the 
buffer, 

mysql> create database myaccounts: 

Query OK, 1 row affected t0,40 sec) 

ntysql> use my accounts: 

Database changed 

mysql> create table passwords( 

-> name varchar[6D), 

-> pwd varcharthO), 

-> userid int(lO) auto„increincnr primary key ) : 

Query OK, 0 rows affected (Cl,08 kcc) 

mysql) select * from passwords; 

Empty set (0.09 sec) 


In Lhc above, I first created a database called 
myaccounts, set myaccounis as the current database, 
then created a table within inyaccounts railed passwords. 
Passwords contains a 60 character name, a 60 character 
password, and an auto-incrementing userid. We then 
verified that the passwords table was empty. 

Let's .switch back over to PUP and mtxlify our code so 
we are writing our passwords tnu) the table. Biick in your 
plain-text editor, replac:e your existing axle with xhls version: 

<btml> 

<tltie>Sample PHP Forra</tltie> 

</head> 

<body) 

<p>Conaecilng to the database,.,</p> 

<7php 

$host = ’lodalhost*; 

$user = 'roQt': 

Spw = *■; 

Sdb = ‘myaccounts*; 

$llnk = mysqLconnect ( $host. $uaer* Spw ) 

or dte( 'Could not connect: ' , mysql„error(J ): 
echo 'Ckinncctod successfully*: 
my s ql_s el bcI_ dbI $db ); 

?> 

<p)If we got here, we've connertndI</p) 

<7php 

if £ Iempty £ S^POSTl 'name' ] ) ) t 
$ienipname = $ POST I 'name* J: 

$teTflppass ” $_P 0 ST f ‘pwd‘ J : 

$query = "insGrt into passwords values ( 

'Sterapname*, '^temppass', fl}"; 

Sresuits = mysql_quGry( Squery ) 

or prlntf( “Query error; %s". mysql,error[) ): 

I 

iitysq t_closeO; 

V> 

<fDt:m actiori="<?php ^PHP SELF; ?)" met hod-"POST") 

Name: 

<input rype="lext“ name="najste" /) 

(hr /> 

Password: 

<input type“’password" naiie=''pwd" /> 

<hr /> 

<input type!:="subait" /> 

</fonii> 

</body> 

</htmi> 

The first chunk of thi.s code should lx; familiar from 
earlier columns. We use mysqlj:tmneclO to connect to 
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the database and my^ql_select_dbO to make the dataf^ase 
the current one for subsecfuenl commands (just like use 
myaccounts; in the MySQL monitor)* 

Chtiiil> 

^head> 

<t±tle>SaDpie PHP FQr6i</title> 

</head> 

Cbody> 

<p>CQnnectin^ to the database.,.</p> 

<?php 

Shoat “ *localhost’; 

Suser “ "root*: 

$pw ^ ; 

$db “ 'myaccounts': 

Slink = myBql_connect{ $host, $user, $pw ) 

or dia( 'Could not connect; ' * mysql_srror() ): 

echo 'Connected successfully’; 

myBql_select_db( $db ): 

?> 

<p>If we got here* we’ve connected!</p> 

The next cliunk of code looks like what we did earlier 
in the column. Instead t>f usinj? echo to print out the form 
fields, we build a query instead and use mys€il_queryQ to 
fire it off. Tliis will insert the row into the MySQL table. It 
is important to note that the Squery line is a single line of 
code. It wraps in this column, but you should enter it as a 
single unbroken quoted string in your source code. 

After tile if statemenl, we close the database. Each 
time this page is loaded, the data base is reconnected, 
worked with, then closed again. Some people pui the 
n7ysqi_closeO at ihe very liottom of die file, just to make 
sure they don’t accidenUiliy place code beneath it. 

<?php 

If ( !empty( S_POSTl ’Dame’ J ) ) t 
Stempname = $_P0ST L 'name' ]: 

$teiappass “ S_FOST[ ’pwd* 1: 

$query = ’’irigert into pas^wordn values ( 

'$tempnarae’, 'Stemppass', 0)’“: 

Jiresults " pyHql_query( $query } 

or printf( "Query error: Xs". iiysql_errorO ): 

myflql^eloeeC): 

7> 


The rest of the code is pretty much the same as what 
you had above, rhe implementation of the form ami the 
dose iDody and hlml taits. 

<fonii aetlon-"<tphp SVIIP.SELF: ?>* nethod="P0ST”> 

Name: 

<Input iype=''text" nanie="name'' /> 

<br /> 

Password; 

<iTiput type^"paECWord** naBie="pwd" /> 

<br /> 

<input type-“i!ub 0 iit'* /> 

C/form) 

</body> 

</htnil> 

Running the MySQL Porm 

Let's lake this puppy for a spin. First, lx.* sure you 
saved your source ccxle and copy the file to your Sites 
folder. In your browser, type this link: 

http://127*0.0.1/-davemark/phpJormOZ.php 


Note that I saved this new version of the source code 
as pbp^orm02.php. Be sure to change davemark to your 
user name. 

Once the table loads, enter a name and a password 
(see Figure 4) and click tlie Submit button. Note that each 
time the page reloads, the database is reconnected* 



Figure 4, Entering the data that will be written to the 
MySQL table. 

Once youVe entered enough data, go back to 
Tenninal and take a look at your table* 


tnysql) select * froni passwords: 

H--- i ---+ 


nuRie 

pwd 

userid 

Frankllti Roosevelt 

Delartu 

I 

Dave Mark 

fudgiethewhals 

2 

Dark He1met 

spaceballs 

3 


1 rows in set ( 0.00 sec) 


Cool! All the data is there* 


Until Next Month... 

There is just a ton you can do wiili MySQL and FJIR 
If you don't have a PHR library already, J found tlic Ixxiks 
MySQL in a Nutshell and Programming PHP from 
O'Reilly and PHP 5 and MySQL frotu Apre*ss a big help in 
getting started* 

Not sure what I’m going to do for next month's 
column* [Ve been reading the galleys to Mark Dalrymple 
and Scott Knaster’s upcoming Leant ObfecUve-C from 
Spiderworks* Hnimm, miglu he fun to explore a )>it of 
dial. Well, we'll see. For now, it's !>ack to Uike Anna for 
a bit more summer laziness. See you next month. © 

WAX 
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A 

Graphical 

Tutorial 

By Emmanuel Stein 


Why Use Encryption at All? 

Some people tliink thiU if tliey are not doing anytliing 
wfong or illegal, diey ck> not need to encrypt their 
messages. The problem with this aigumeni is tliat it 
assumes one is trying to prefect a message from some 
government authority or law enlbirement apparatus and 
ignores the very renrl risks itSvScxiated with tlieft of 
intellcauiil pn)tx^rly via a)r|K>mLe esjricmge. Tlic fad. is, 
that almost anyone with a bit of networking knowledge 
can easily "sniff’ your message off tlie network and not 
only rc^ad it, but m-write it and .send it along to the 
intended recipient witliout you ever l>eing aw^ie (tliis is 
called tlie "man in tlie middle attack”). Lising GPG, you can 
thwart these would-lx; crackers and do so transparently iiy 
using GPG to encryj>t yt)ur mail mes^ges. 

GPG in a Nutshell: 

GPG employs public key, as well as symmetric key 
ciyptogntphy, to perform its nragic. Wlien setting up GPG 
you have several options for generating your keys. Tlie 
default of^ion uses DSA to generate your priimry keypair 
for signing, and then generates a secontl (also called 
suht.irdinate) keypair that uses HlGninal for encryption. 

Although we are using the niore stjphisticaied 
primary and suboidinate designations to explain what 
gets generated in GPG, both the primary and 
subortiinalc keychains arc usually, for praciical 
purposes, tliought of as a single keychain. In this 
scheme, you have a public and a private key. Your 
private key is secan and should lx* treated as such. 
Take precautions, and do ntjl lose it as you will have 
to regenerate the key and will not be able to read mail 
encrypted witli your original public key. You do, 
however, liave ilie ability U> revoke a key that is 
compromised. Unlike your private key, your public 
key should lx* widely distributed, allowing others to 
send you an encrypted message tlial only you can 
decrypt waih your private key. 

GPG uses the .same approach to key management 
as PGP, whicli is uj say via a "web of trust." Rather than 
employing a centralized ceitification authority such as 
Verisign, GPG allows individual users to aa as their 
own cerLiftcaiion aulluJiily. TItere is an infrastructure in 
place for the GPG community of well-maintained 
keyservers that facilitate exchange of public keys 
among users. 

GPG and Apple Mail: Two Great 
Tastes That Go Great Together! 

For this tutorial, we will focus on enabling GPG in 
Apple Mail 2.0 using the GPGMail plug-in. Links to sites 
where one can t>btain GPG mail extensions for other 
popular mail clients will also l>e included. 
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How GPG-Enabled Mail Works? 

Befort: we dive into selling up mail for GBG, I will take a 
mojoenl to review how GPG works in the context of email 
communications. When you want to semd an enciypied 
message l(> a colleague or friend, you encrypt the message 
using iheir public key, wlucli may he obtained ilirectly from 
that individual or via a keyserven The recipient ilien will 
decrypt your message using their private key. Signing is also an 
important part of GPG-enahled mail commitnioitions, and 
involves using your private key to create a digital signaiure that 
guarantees to your recipient timi the me.ssagc came from you 
and has not been tampered with. 

GPG Install How-To 

What you need: 

Go to http://nnacgpg,sourceforge.net/ and download the 
following rcHfuired applications: 

• Gnu Privacy Guard (aka GPG) 

• GPG Keychain Access 

We will not be tTwering the excellent suite of file utilities also 
available ai iliis site. Nonetheless, you are encouraged to explore 
these binaries at your leisure, as they may prove extrt:meiy Lisc-ful 
for non-mail GPG openitions. 

In oaicT to enable GPG in Apple Mail, you will also need 
to obtain the GPGMail application at 
http://vvww.sentexh/software/GPGMail/EnglishJproj/GPGMai! 
,htmL 

If you arc a security consdous person, and are deploying this 
package for a tiiiSsSion critiatl applicaii<m, tfien you may want to 
chec'k crach packages authenticity via ics MD5 cliecksum using die 
opt!assl command in tlie tenninal 

Installing Gnu Privacy Guard 

Double dick on the GnuPG .dmg file in order to mount the 
contents of the archive, lb install GPG, double dick on the GPG 
,mpkg file to invoke the installer. 

Once GPG has installed successfully, we will need to 
generate our keypair. To simplify the prtKess, we wilt use the 
GPG Keychain Acceiis application rather dtan the terminal. 
This application is modded after (he intuitive Keychain 
application in OS X and is very easy to use. Simply unzip the 
folder called GPG Keychain Access and drag it into the 
Applications folder. 

To generate your keypair, open the GPG Keychain 
Access application. 'I'he application will notify you that you 
do not yet have a keypair and offers you tite t>ption to 
gencmite one (Figure 1). Also, this dialog gives you the option 
to import your secret key, 7'his is useful when you want to 
configure a second computer with GPG. Your private or 
secret key will l>e created in your home folder under the 
hidden gnupg directory. 



Figure Keypair Generation and Import Dialog 


To create a new keypair, select tlie Generate option in tlie 
dialog (Figure 1) to invoke the install wizaal. You will lx: given 
several optioas forgeneraling a key (Figure 2). Ii is recommendetl 
that you select tlie default option, DSA and EIGamal as it offers 
the most flexibility' and Ls required for ttse witli mail since die 
other optioas only allow for signing imd not encry[Ming. 




Mjik« i nvw kjty 



Seleci the Kind Key 


Pleiu iclect whii kind of key you 


V DSA ai4d OGAinat 
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Figure 2. Key Generation Wizard: Algorithm Selection 


Once you have selected your algorithms (basically the 
functions used to scramble and de-scramble your data), you will 
lie asked to chcxise a kc 7 -icngth. The general rule is, the longer 
the Ix-ttcr. Without getting into the demils of encryption math, 
the security of your key increa.ses exponemially with key length. 
The only pritential down side to a longer key is the additional 
time it lakes to generate and to perform its encryption 
0[ierations, Neverthele.ss, w'ith a Mac of recent vintage you 
should not notice m(>re than a miiiiitial lag when performing 
any GPG otxTJtions like enciyption and decryption, even using 
die longest available key. 

Following the seleciion of a key length, you will be 
pre.senled with the option of specifying an expiration date. While 
ill is may be useful in some envirejnmenrs, ii is rather limiting and 
therefore not recommended unless you have a specific need. 

Next you will Ik- asked to provide your identiflairion data 
such as Name, Email Address and an optional comment. It is good 
fonn to use your real name as you are taking die responsibility of 
a self-certifying aullioriiy. So he honest. 

You will dien be prompted for the pas.sphrase to protect 
your private key. Check over your configunttion options, and 
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correct them via the Go Back button, or simply press Continue 
to gencnite your keypair. A lengthy keypair may take 30 minutes 
or more to genemle, so a coffee [>reak may be in order. 

When your keypair generation has completed, you will 
see you new public key in the GPG Keychain Access 
Applicati<jn (Figure 3). You can see the sul>key we spoke of 
earlier, by clicking on the disclosure triangle. 



Figure 1. View of Sub-Keys Using the Disclosure Triangle 


lb install die GPG Preference Pane^ select the Preferences 
option in the Application Menu, Click yes in ilic dialog box that 
pops up (Figure 4), 



Figure 4. '"GPG Preference Pane Not Installed" Dialog 


'llie GPG Preferences insLiller will then walk you dirough the 
installation of the GPG System preference pane (Figure 5), 
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Figure 5. GnuPG Preferences installer Invoked via the 
GPG Keychain Access Application 


Once the GPG preference pane has sycccssftilly insmiled, lire 
up tfie System Preferences iipplication and click on the GPG 
Preference pane to explore the various configuration options. 
When you first open die GPG preference pane, you will lie asked 
to chcKise t rrF-8 for string encoding (J'igure 6), Select the default 
Please Do option to ensure proper GPG operations. 



Figure S. GnuPG Preferences Pane and UTF String Encoding Dialog 

You may use tills preference: pane to customize GPG, Don't 
let all these available options overwhelm you, though, and keep 
In mind that the defaults are fine for most folks. 

Managing your GPG Keychain 

GPG relies on a centralized key managemeni system of 
keyservers. tlpload your public key to a GPG keyserver 
(private kc 7 not accepted!) to enable others to send you 
encrypted messages. 

In the GPG Keychain Access applic^ition, click on your 
public key to highlight it and then select Key > Send to 
keyserver (Figure 7). 



Figure 7, Send To Key Server Menu Option 


Upon selection of this option, a temiinai window will pop up 
and auLomatically run the terminal commands for sending the key 
to a keyserver for you (Figure 8), 
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Figure 8. Invoked Terminal Session: Sending Public Key 
to a Keyserver 


Now that you have made you pul:>lic key availahle to others, 
yoti will need lo download your correspondent's pul^Iie keys 
using ihc GPG Keychain Access appikation. You cun also 
download public keys via ilie mail interface, which will lie 
covered in ihe next seciioa 

Click Key > Search for Key (Figure 9). 



Figure 9. Search For Public Key Menu Option 


You will be prompted lo enter a search parameter (Figure 
10), whic:h is typically your friencrs email address. 



Figure 10, Search For Public Key Dialog 


Onc'e you have entered the enmil address and clicked on the 
OK InUion, a new temiinal will appear and automatically exccuic 
tlie required GPG comntand. If your search lums up a jxihlic key, 
you will be prompted ro download it to your GPG keychain. Ihis 
step will retjuine you to select tlie public key(s) for downloatl. from 
within the terminitl. In the illustmtecl example (Figune 11), we see 
Ed Marczak's public key as^sociated wiili tlie enniil address we used 
In the search field. Once you make your selection, you will see 
output in the lennimil cxiiifiriTiing the dow'nkiad (Figure 11). 



Figure T1. Invoked terminal Session: Downloading Ed's 
Public Key 

To view^ the newly imported public: key in the GPG Keychain 
Access application, go to Window > Refresh, 

Once you have u|)!oaded you public key to the GPG 
key servers and downloaded your correspondent's public key(s), 
you are ready to install GPGmail plug-in tor Apple Mail 

Apple Mail With a Side of GPG(Mail) 

Double-Click on tlie GPG Mai I .dmg file to reveal the mail 
liundle and install script. If Apple Mail is open, be sure to quit 
the application before continuing. Proceed by double-clicking 
on the Install GPGMail AppleScript and click Run in the dialog 
that pops up. Once the installer finishes, a dialog !>ox will 
appear Click on the Launch Mail lo start the Apple Mail 

To configure your GPG mail preferences simply go to Mail > 
preferences > PGP (PGP and GPG are often used interchangeably 
by the application’s developer) shown in Figure 12, 



Figure 12. GPGMail Preference Pane 

The default configuration shouki get you started, although, as you 
use the GPG mail bundle you may want lo change several 
pantmeters to suit your use of encryption. 
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changes to the Mail Interface 

Ono: you insiulJ GPGMaO for Apple Mail, you will noticx; 
new menu items. Tlicse include GPG Keys under the View menu, 
which cxjntrol the display of GPG attributes in Mail. (Fi^ne 13) 
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Figure 13. PGP Keys submenu in the View Menu 


^llie second menu addition, PGP Ls lcx:aLed in the Message 
menu. This submenu can be used to access common GPG 
operations as detailed in Figure 14. 



Figure 14. PGP Submenu in the Message Menu 

A final added menu items is the PGP Key Search function 
in the Window nienu, which lets you search and download 
public keys. This tool also pt>ps up when you attempt to 
encrypt a message and send it to a redpiem for wliorn you 
have not yet demmloaded a public key (Figure 15), 
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Figure 15. PGP Key Search Menu Option and 
Accompanying Dialog 


Tilt; results will Ire returned in a PGP Key Search dklog lx)x, fntm 
which you will Ixj ahle to download the required key (Figure 16). 
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Download FCP kev? key server 

OiOdae which k m vov w^t to download and IrnpOft in your keynny _ 

£>ei€dfl'i7on j 

T® QjitCECSJlD. DSA aoj4 hitsi. cr^aicd on Tuesday, /une H, ZOOsTt 
I mmanuel SieIn <macv«rse^mac.£om> 


Found 1 marebing k«y(i) 


C CMKet ) f Downteal) 


Figure 16. Downloading a Public Key in the PGP Key 
Search Dialog 


The public keys that you download using PGP Key Search 
will be available globally to all GPG key management 
interfaces, such as the GPG Keychain Access application, 

One of the most obvious changes to the mail interface is ihe 
addition of checkboxes (Figure 17) for signing and encrypting tluit 
appear in each new message window. 



Figure 17, Check Boxes for Signing and Encrypting in an 
Apple Mail Message Window 
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Wlicn sending m encrypted mail, by default, die message will 
Ixi enaypred wiih the public key of die recipient. However, you 
am explore die encrypuon options in die Keys tlnip down menu 
next lo die Encrypted checkbox to generate, for iasiance, a message 
password, which uses symmetric' key encryption to scramble the 
message and for whidi die recipient must know the piLsswtjrd. 

Althougli, I encourage you to explore all the available 
oplioas, you can effectively use GPCp witlioul ever having to 
touch the drop-down menu or GPGMail preference pane. Jusi 
use the checkboxes* to sign and/or encrypt your 
cximniunications as needed. By defauh, Gl'GMail automatically 
turns on the signing and also tunis on encryption when it 
detects a redpienl wliosc j>ublic key is in yoor keychain. 

When you send an encrypted mail, you will l^e prompted 
for your pa.ssphrjse, created during the generation of your 
keypair. Once it is entered* (Figure 18) your message will lx; 
encryptetl and then sent. 



Figure ia. Message Encryption 


Effortlessly edit your PDFs 



PDFpen 


Now you can fill out and save forms, 
split, combine, search and even 
scribble on your PDFs with ease! 

"4 mice"- Macworld 


When you receive an encrypted message, press the decrypt 
button in tlie message window (Figure 19). You will l>e 
prompted to enter your pa.s.sphrase in order to decipher the 
message contents. 



Figure 19. Message Decryption 


Notice that in Figure 20, the disclosure triangle has been 
expanded to display the lime and date when die message was 
either signed or Ixjdi signed and encrypted. You may use die 
signing infonnadon to verify the authenticity of the message. 


$49.95 - download free demo at PDFpen.com 
Also available: PDFpen Pro for creating fillabte forms 
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Final Thoughts 


Figure 20. Decrypted Message Contents 

GPGing Other Mail Clients 

Although we hnve focused on Apple Mail 2,1) for Tiger, 
there are several good mail client extensions available for 
popular Mac mail clients. Please find the UKLs listed 
hcUmi 


The right to privacy has come a long way since 
1991, wlicn PGP was first released. With the nation in 
the midst of the first Gulf War, government attempts to 
cimatl privacy and free speech threatened lo suppress 
emerging mass encryption technologies like PGR In 
fact, the Senate passed the omnibus anti crime bill 
(5,266) in 1991, which effectively banned the use of 
high-grade public key cryptography altogether! 

Only through the efforts of the brave few who 
leaked PGP onto the Internet in 1991, partly in protest 
of the Senate bill banning the use of strong 
cryptogra]>hy, did government attempts to stifle 
innovation and invade personal privacy bec:ome moot. 
So, next lime you send an encrypted message (or use Apple’s 
MleVault for that mailer), tip your hat **ro the crazy oftes, the 
misfits, the rebels, the trouble makers, the round pegs in the 
square hoieSy the ones who see things different They are not 
fond of rules and have no respect for the status quo, because 
the people who are crazy enough to think they can change 
the world are the ones who actualiy do.*" -Apple Corp., 1999 




Mozil!a/Netsca(Xf Commimicaior/lliiindertjird uses enigmaU, 
which may be obtained at http://enigmail.mozdev.org/ 
index.html. 

For MaiiSniiih Users, Alex, has some great uiols ffjr 

encr>^pTing and decry f)ting in this program; see 

http://a!ex,primafila.net/Matlsmith-GPG 

Eudora faas will find a host of useful AppieScripLs for 

encryption and decTypiit>n at httpV/ mywebpages.comcast.net/ 

chang/EudoraGPG/ 

Finally, for those using Kntourage X or 2(XM, a plug-in is 
available at http://entouragegpg.sourceforgemet/ 
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MAC IN THE SHELL* by Bdward Marczak 


DNS And E-mail Part 2: 
Troubleshooting 


How And Where To Look For The Source Of Trouble. 


Y OU know that something isn’t working right. Perhaps you’re 
not receiving mail, or worse, the users have noticed before 
you have, and now your phone is ringing. But witere do 
you start looking? What tools can you use to root out the problem? 
If you’re wondering about the answers, read on. 


Hello Again 

liist mm\l\ we got into DNS and e-mail 
and how LI 1 C 7 relate. ThL-s month Is ptirt 2, 
and depends on part h We intcj 
hxsic troiihk^shooting, but there's more to the 
equ:ilk)n. If you're setting things up f(>r the 
first time, you tend to mn into DNS related 
Issues. If tilings liave lieen up and running for 
a bit, and then .suddenly stop, there's another 
range <jf Issues tt) Itxjk al But for me, it all 
j^aris in one place. 

Sunday Papers 

Always look at the logs. IVe said it 
lieftjre: logs are tlie liearl of ihe system. If 
you’re a .S 7 stem administrator, you sliouid 
always be monitoring the logs. Always. 
Partially by eye, partially by scripr that will 
alert you to problems. In ilie case i>f mall 
the logs are going to teU you one of two 
things: the prol>lem Ls directly on your 
system, the mail server, t>r, die problem lies 
elsewhere, outside of the mail server. In ilie 
fonner t:ase, there’s either database 
corruption or a simple misconfiguraiion. In 
the latter, while it can lie several diings, I'm 
[Killing on DNS as rhe culprit. 


On The Outside 

Id’s start with this Gise: youTe getting calls that inbound mail 
isn't showing up. Or, |x,^iiiaps you just .set up a server from scratch 
and notic'ed this for yourself. Wliat do you do? Check the logs. 
Specifiailly, /var/log/mail.log. In one case, you’ll send e-imiil from 
an ouiside test aca>Linl (GMail, I'm kxikirtg at )o«), and the logs will 
siiow...nothing. Nada. No iiKiveinent. Well whafs wrongs 

This can he one of three things: 1. Posifbt just isn't running 
(this should lx: unlikely, as watdick)g/l;iunchd take great pains 
to make sure jxjstfix is always going. Bui hey, it can hiippen). 
2. Your firewall/roiiter isn't allowing the SMTP [>rotocol to reach 
your mail server, or 3^ Outward Facing DNS isn't correct. 

What Can 1 Do?!? 

In tlie case iliat Postfix isn’t running, start it! It may lie that 
simple. If yoLi've been toying with tlie corifig files by liand (or 
you liave some disk {'orruption), there may Ix^ sometiiing 
preventing it. How will you know? Cbt'ck ihe iogsl When you 
start Postfix, by Servrer Admin or CH, wateh /var/log/mail.log. If 
there’s a problem, it It tell you. 

In die case wliere yr>ur firewall isn’t configured correctly, 1 
unfortunately can't help you directly, but merely point it out as a 
murve of problems. There are inany, many, many varieties of 
fuewid] out diere, along with many ways to have a network 
configured. I can’t speak to litem all In the general sense, 
though, port 25 for SMl'P must l3e able to traverse your firewall 
reach your mail server, and your mail -server should 1 .x able to 
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reply via the same [)at]^ ~ most services aren't ax)j with 
asymmetric rxrutiiig. 

Tlien iliere's the case where tlie world just doesn't know 
how to send you mail. 

Contact 

As 1 touched on last months DNS plays an important role in 
the dcliveiy of e-mail. Specifically, when a mail seiver needs to 
deliver a piece of e-mail st anew here other than its loc’iil self, it 
queries DNS for the MX record of the recipient's domain. 

If someone on the outside wtrdd is tiynng to send you mail, 
the DNS server they're using had 1 Hotter be able to get their mail 
server an MX record for your domain. If it can't, their mail wiU 
sit in tlieir kKal queue for a bit. 1lie ttx)! for diis jol) is dig - tlie 
domain information groper. 

By default, dig will l(x>kup DNS ‘A' records, similar Uj llic 
now deprecated nslookup: 

$ dig iifww.GXjtmple.com 

; «» DIG 9.2.2 <<» wvw.Gxamplo.com 
:: global options: printrmd 
:: Got answer: 

:: ->>KEADER«- opcode: QUERY, status: NOERROE, id: 894/ 

:: flags: qr rd ta; QUERY: 1. ANSWER: 1. AUTHORITY; 2. 
ADDTTTONAL: 0 

:: QUESTION SECTTON: 


: WWW ,example,cora. 

IN 

A 


;; ANSWER SECTION; 

WWW, example.com, 1/2800 

IN 

A 

192,0.34.166 

AUTHORITY SECTION: 

example,con. 21600 

servers.net. 

IN 

NS 

a, Ians- 

example.com. 21600 

servers.net. 

IN 

NS 

b. iaria 


:: Query time: 41/2 msec 

:: SERVER: 192.16S.100,I2#&3(192.IfiS.lOO.12) 

:: WHEK: Tue Jul 19 23:56:43 2005 
KSG SIZE revd: 97 

Gives US quite a bit more information than n.skx)kup, too. I he 
quick way to took at this Ls: 

Question section: what was asked of us? 

Answer .section: the answer to live (|uery, if possible. 

Authority seclion: which servers are authoritive for the domain 
in cjue.slion. 

We, however, need to check the MX record for our site. 
Let's look up a domain that has a nice, clean example. 
Here's an example from my favorite example, GMail: 

$ dig NX gtnall. com 

: <<» DIG 9,2,2 «>> MX graail.com 
:: global optionf;: printettnd 
:: Got answer: 

-»HEADER«- opcode; QUERY, status; NOERROR, id: 12756 
:: flags: qc rd ra; QUERY: I, ANSWER: 5. AUTHORITY: 4. 
ADDITIONAL: 4 

:: QUESTION SHCTTON; 


:gmaii,com. 

IN 

MX 


ANSWER SECTION: 

gmaii,com. 3600 

IN 

MX 

jO gKmtpl71.google.^ 

gman.com. 3600 

IN 

MX 

10 gsratp 185. google.* 

gmaii,com, 3600 

2 , google.from. 

IN 

MX 

10 g*jmtp)71’ 

gmaii.com. 3600 

2. google.com. 

IN 

MX 

10 gsmtpi85 

gmaii.com, 3600 

in,i.google.com. 

IN 

MX 

5 gmaii-stntp’ 

:: AUTHORITY SECTION: 

gmuH.com. 86400 

IN 

NS 

rm3.google,com. 

gmaii.cum. 86400 

IN 

NS 

n!j4. googlc.com. 

graail.com, 86400 

IN 

NS 

nsl.google,com. 

gmaii,com, 86400 

TN 

NS 

ns2. google.com. 

ADDITIONAL SECTION; 

nnl.googIe.com, 276050 

IN 

A 

216.239.32.10 

ns2.google.com. 276050 

IN 

A 

316,239,34,10 

na3.google.com. 276050 

IK 

A 

216.239.36.10 

ns44googlc.com. 276050 

IN 

A 

216.239.38,10 


:: Query time: 46 msec 

:: SERVER: 192.168.100.12^/53(192.168.100.12) 

;; WHEN: Tue Jul 19 23:19:04 200,5 
HSG SIZE revd; 306 

first thing lo point out: witli dig, you can simply give it tlie record 
type llial yoifre after Back lo e-matl: notice dial in a proper .setup, 
tlie answer section conUiins all mail .servers, along with iheir 
priorities. RememlxT: the lower the number, the hi^bef the 
priority. Also notice tliat in the aaswer .seaion, each record ends 
witli tile itx)t node - the doi gniail-soitp-in.l.googie.com is 

the highest-priohiy mail server. All mail deliveries slK>uld be 
iitiempted liiere first. Tltis b followed by 4 Ixickuti servers that liave 
equal priorit>^ If the main .server Ls down or unrt^ichable, outside 
mail serv'ers will chixjse one of tliese to deliver to. 'The algoritlun 
for this LS actually a little more complex than you’d think at first look 
- it doesn't simply chtxxse tine at random. 'Hiis algorithm is parr of 
a deeper discussion, thougli. Once tlte main server is back uj), tliey 
will hand off ilie mail iliat they've queued up. 

Naturally, you should have a Ixickup mail server, and it sfM)tdd 
reside at a separate kxaiion on a separate nemTirk. If you can't 
configetm iliLs youiself, your fSP wiU very often act a,s a Ixjckiip MX 
for you. I've tilso help^ witli some creative arrangements where 
companies will Irackup eacli odjer. Just be aware that mail ihal gels 
queued on a trackup sits tlieie unencrypted, sri you need to trust 
your Ixickup paitner. This b, actually, a gcxxl reason to start 
erKTypting e-mail yourseif. Check out tlie GPCt article in lhi.s Issue 
by KmmanLiel Stein for instructions on just tliat. Additionally, 1 have 
an inlnxluction to GPG, digital cerrifitaies and why I sign on my sire 
at http://wwvv.radiotope.conaAA^itin 

dig is happy to query other DNS servers. In the case of 
mail, you need to do this. Make sure youVe querying a sender 
outside of your LAN so you’re getting the same perspective as 
the world, ^^un it like Uiis: 

dig §199.184,165,1 MX yourdomain,com 

(199.184,165,1 is an actual DN5 server - be kind: don't haimiier 
servers that are open to the public. Find and use die DNS server 
provided by your ISP.) 
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If DNS ts the ailprit, whaf's wrong? Did iJio tbmy into dig 
shine a light on the is^sue? Were diere any surprise or missing 
entries? Malformed entries? Mail server priorities set correctly? 
As you inn see, there are a lot of 'i‘s lo dot and I's to cross. 
Computers can lie sensitive to rliiit kind of tiling. 

If your DNi> is correct try the telnet trick from last month’s 
column. Hither mail is getting through, or it isn’t. If mail inn't 
penetrate a firewall, conreti DNS won’t mxike a difference. 

Inside 

if your setu[> passes die DRS test, what’s next? To the logs! 
You should still be looking at /var/log/matUog - preferably in 
a lerrninal using ""tail -f so you’re watching it update in quasi- 
real time. 

IHiis is a quick refresher regarding the e-mail subsystem. If 
you need more depth, please refer to pan 1 of this article. 

Tlie first tiling Ki remember is this: fe-rnaif, akiiougfi 
typically viewed as one single entity^ is traditionally many 
sepamte pieces. In our case, Apjile uses Postfix for smtp - the 
server receiving e-mail from the outskle world, and from your 
mail client, and they use Cynts for POP and IMAP - yoor mail 
client checking mail. All of these components have convenient 
acronyms to go along with thcin (Wckj! More acronyms!): 

• M'lA: Mail Tmnsfer Agent - your SMll^ server, as it\s 
responsible for imnsfernng mail. 

• MIJA: Mail User Ageni — this is your e-mai! afifilication such 
as Eudora, Mail.app or Pine. It s the user interface into the 
mail store. 

• Ml^A: Mail Delivery Agent - This is a prognim that is 
responsilile for gelling the mail from the M'FA and dropjiing 
it in the mail store. 

Traditionally, your MTA (such assendmail) would rc^ewe mail 
(internally or externally), and know' how to get it into the system 
mail spfK)l all by itself, 'llie system mail sixk)I I’onUiined mailtioxes 
for each user on the system, and it would do so using i!ilx)x fonnai. 
mixix b the traditional UiiLx mitillxix formiit. It stores ali mail for a 
single mail ibkier, like your inixix, in a single, laige text file. As you 
can inugine, this d<Kisn’i .stiile rex) well How many |)eof>le reading 
thi.s article have, or blow .stjmame who has, an inlxix tliat’s over 
50{)M1^? How alxiut 1GB? Yeah, it liapfK^ns. 1b keep all of rhit in 
a single, un-indexed text iile cm cause you some iierfonnancx! 
issues. (Jn the otlier end ol' this, a MDA. like ‘miiir or [line, would 
know how ro reach into thit same mail store and ilisplay mail to die 
end user. Gyms changes all ot' ifett, so tliLs dLscussion will kxiLs on 
wlmt we am dealing witli. 

Subdivisions 

If yoLiVe never touched A[>ple’.s stexk mail config, you -should 
very raarly see prfiblenis, Now diat ilie log rolling hug has been 
fixed, you almast liave lo Iryf to destroy Cyrus. See part 1 on ways 
to detect and troubleshtxx Cyrus issues. Postfix is typically just a 
rtxk. But we’ne techs, light? W'e ain’t leave well enough alone! 
We can inifirove it! Or, more likely, your employer or your client 


ask you alxmi some functionality that doesn’t already exist in 
Apple’s config. Thankfully, 10.4 Server Ixings us integrated 
Amavis wiih ClamAV and SpamAssassin. However, die now oft- 
most requested item “ vacalion replies - is something you Ixive to 
deal with, (This should l>e liandled by sieve, liut if was broken 
under 10.3| and currently reniiiins so under 10.4.2). 

While Postfix has several rabies and files, two really cover 
the vast majority of configuration: main.cf and master.cf. iTiese 
are stored along with the rest of Postfix’s configuration files in 
/elc/postfix. If you are ever tempted to make changes lo llie.se 
files, back them up first! Il 1I take you two seconds to tar them 
up (tar czvf -/postfix-date ’+%Y%m%d%H%m'‘.taf.gz /etc/postfix), 
or just simply copy them. You 11 be much happier that you did 
when things stop working, and you need to go back to things 
the way they were. 

tnain.cf is the global configuration file for Pcxslfix. When 
you edit infomiaiion in Server Adinin (or Postfix Enabler), 
you’re altering this file, main.cf is primarily responsible for 
defining the service’s role- 

What domain to receive mail for. 

What destinations to relay mail to. 

How to deliver mail (direct or relay). 

Tile domain to use in outbound miiil 

Clients to allow relay from. 

A[iple includes a default mainxf file in /etc/postfix. Server 
Admin just tacks the paraineiers that it changes onto the end of 
the file. So you 11 find two values for tenain parameters. Tile 
second will override the first* so Apple’s method is OK, In some 
ways, it’s nice tfiat all of the values ir changes are grouped, 

1'he fonnat of main.cf is simple: parameter ^ value. Like a 
Unix shell variable, you can use the value ofilie parameter later 
on in another parameter like this: parameter = $other_paraniier. 
Interestingly, since Postfix does not ctsmpute the value until run 
lime, you can use a variable before you actually assign anything 
to it. The lesson litTe is that one reason Postfix may not start 
is that nutin.cf ts mangled. Hie one parameter that nuist be 
right here is ’’mydesttnation” - this should contain all domain 
names that Postfix will accxrpt as local, and hand off to ‘deliver’. 

Any time you make changes to the configuration files, you 
mu.si issue a postfix reload for Postfix to jiick u[i the c'hanges. 
I've seen peofile make changes, and then wonder why the 
changes aren’t working. No postfix reload, no changes, 

More likely, you find some nait addition to Postfixj and the 
iastruaioas ask you lo tmxlily^ rrtister cf. master.cf aintrols Postfix’s 
iniisier process, whicii in turn controls all Postfix child piTx:esses. 

Each line in master.cf defines a service in Postfix. The order 
dix:sn’t matter, however: a) you define a service multiple times, 
only the last one Is honored, and li) it’s smart to keep logical 
groups togetlier, for your own sanity. Empty lines and comment 
lines (liegin with are ignored. A logical line Ixrgins by liaving 
non-whitespace text in column 1. A line is continued by having 
white-space precede the text. Eacfi line has 8 cxilumns. Ibe 
man page can do a better job of explaining die basics than 1 c^an. 
Unfortumilely, Apple doesn’t indiide this man page, so go check 
out http:yAAAWv.postfix.org/master.5.htmL 
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The part that tends to throw |x:o|)le off is takin^^ generic 
installation instructions and iiitxlilying them for OS X, Sometimes 
an installer will try to put a bimiry or sc'ripl in a location that is 
not in your path. Postfix ftlteni slKJuld never be run as r(K>t, so 
yoifil need an additional system user to am filters. However, 
most generic instnictions tell you to add a user using adduser - 
present on all IJnkies but OS X (not by default, anyway). 

Tliere are three ways to get a filter to run: glohaily, l>y placing 
a ct)nteni_filter= statement in inain.cf, by specilying a content filter 
fur a given patli (masterxD, or, by ainning a filter on tlie fly, based 
on some criteria (altering lo<^kup tables or checks). 

Tlie first method is the most sitnple, an<l is used by Apple 
to hook Amavis into Postfix. Note the last line of mainxf on a 
Hger Server: 

content_fllter ^ {^atp-amavls: [12/,0.0. t] : 10024 

'ITiis inakcs Postfix nm all ciiiened mail through a filter 
called smtivamavls. How ckx?s Postfix know what *‘smtp' 
amavis” It must be defined as a seivice in rnaster cf. Yog'll 
see that mastercf has this definition (under Tiger): 

smtp-amavis unijt - - y - 2 sjnrp 

'Hits content filler line in matn.d" will lake all mail and am it 
througli the filter “smtp-amavis”, and that's really wliat we want 
for an anti-vinjs filter However, if, for some rea.st.)n. we wanted 
tliis filter to nm only for incoming mail, we have to renrove the 
content Jlter siaiement from main.cf (tltat's global, rememlx?r - in 
and out) and redefine the snap service to luive two unique 
instances: one for inlxamd and one for ouilxnmd, Tliis needs to 
Ix" done by port, or by IP address. This lenrLs to confuse (X'ople 
that are running with one physical interface. 

llie easiest way to handle tliis is to liave two IP addresses. 
You eitiier need two physical interfaces, or you can multi-home a 
single inLcrface. Tlien, you can add a line in inastercf that applic's 
only to the outlxxmd interface: 

<outWund ip>:srntp inot n - y - smrpd 

-o content_tit.ter“siitp amsvia; 

Ihe “ o” fiag overrides a miiin.cf parameter, fn this case, 
we'll only fikcT if mail is traveling over the outbound ip. Also 
note: tliere is never any while-space surrounding a in 
masier.cf. The trailing after tile filter name is imjxirtunt! 
When left tilank afterwards, it means Tor all domains'. 

Anodier way to handle different routes for different filters is 
to use different ports. Naturally, this is dependant on the filter 
itself, and the protocol involved. For example: wfiile server to 
server smtp would be tough to change from the default of poa 25, 
you can certainly tailor your subnussion port to .suit your needs. 

Tlie third way is a bit more dynamic. Postfix will let you 
filter on the fly by using the access table or header^check and 
body .check njles. 

A great feature of Postfix is that it pcrfiimis filtering after 
mail is in tJie queue, but before it gets delivered. This way, if 
there's a problem w'ith the filter, mail doesn't tx)unce, but simply 
gets queued up. You’ll see this in ihe logs as "status^^deferred”. 
Check your mail queue by typing "mailq” at the command fine. 
You'll see something like tliis: 


// tflflilq 

7-Queue ID- -Size- Arrive! Time— 'Sender/Reciplent^- 

78EF0949EA 710 Tue Jaiv J1 20:43:31 ? 
no Tue Jan 13 20:43:31 7 
(deferred 7t.ranspott) 7 
“ 1 Kbytes in 1 Request. 

In the case where you see “deferred”, you netxl lo take care of 
the filter, <ir remove it by commenting it out of l>oth main.cf and 
master.cf RememlTer from Iasi motitli, a ‘deferred' condition can 
also apply to Cyncs’ deliver agent not Ixing able lo, CT....dcliveii 
If you can fix your filter (a scx ker based fdter may .simply 
need to Ix' lestarted, a pipe ba.sed filter may need some re¬ 
coding), great. You should simply have to postqueue -f to Hush 
the queue and have Ptjstfix make re-delivery aitcmpts. 

If you’ve rcniovecl the filter (lemporarily, right?), you need 
to re-queue the mail, otherwise it w'ill keep trying to deliver 
itself through the old (now non-existent) channel. Do this, as 
root (or use sudo), with rhe poststiper command: postsuper -r 
ALL, followed by a postfix reload. Watch the logs and your mail 
sliould .start flowing freely. Follow that up by another mailq. 

Learning To Fly 

This isn't the enti - we’re just learning to fly. Hopefully 
lliesc troubleshooting guides help you find some of the trrmblc 
in ;m e-mail system should you run into it. As I say each month: 
w^atch the logs! Tills is the heartlxat of your system, and it'll let 
you know immediately when there; is a problem. 

Nalunilly, there on be other problems that crop up in the 
OS X mail .system: mailman issues, other cusloni work or 
iastallations that may grab a port on you, etc. Tlie best way to 
learn how something works is to watch it fail - and then 
reinforce that by diving in and fixing it! 

Next month, we’re going to take a break from e-mail and 
DNS, and get back to .something a little more straighl-forw'ard: 
the Terminal, and one of my favorite utilities, "screeir. 

P.S. : 

jolimiy Cash - Hello Again 

joe Jackson - Sunday papers 

Dingo lk)ingD - On the Outside 

Ice CLibe (not .3^ Special) - Wliat can I do? 

Stereolah - Comaci 
Buzztxxks - Inside 

Rush - SulxlivisiorLs (to all you ACNs tliat landed at YY2 for camp!) 
Pink Floyd - fx:;aning To I'ly 

Yill 
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tedaiidogf amsidtmg ion^Moy that implements 
fliotf servers and im»/ automation. aof 
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am/ two doubters. Get your moi/ on at 
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DevDepot has it all! 



DevDepot sells the tools, toys and technology to put more rhuscle into your Mac. Visit our 
online store today for special offers and great new products, www.devdepot.com 


Television is about to get a whole lot more intere sti ng.^ 


EyeTV 200 


The hJture of T^vi^cb ^ 


m 


NOW ONLY 

$32499 



Watch TV on your Mac! 


Pause live tv! Record, edit 
and archive! -- 






go 

digital 

Convert your analog 
video tapes to 
digital in realtime, 
then burn them 
to DVD! * 


Watch TV on your Mac 

EyeTV features a 124-channel cable-ready analog tuner and DVD quality 
MPEG-2 video encoder. 

Record TV on your Mac and Archive to Disk 

Collect and organize your favorite shows to watch whenever you want, 
then update video content to DVD.* (Toast 6 Titanium required). 

Don't miss a thing 

Use EyeTV's Electronic Program Guide to find exactly what you are 
looking for, and program EyeTV to record it. Program EyeTV from 
anywhere via the Internet. 

_ _ Features and Benefits 


NEW! 


..y 



Record TV otn Your Mac 
Edit Out Unwanted Content 
Archive Recorded TV To DVD* 


• MPEG-2 Video Encoding 

- Digitize Analog Video 

- The Speed And Power Of Firewire 


EyeTV now lets you 
export to iMovie®, 
DVD® and DVD 
Studio Pro®, making 
it easier to create 
professional quality 
recordings. 



























More Great Products! 


ft Buy Today and Save! 


SYNCBOX 


Transfer data from your USB devices with 
the touch of a button. 



* Never run out of memory space again! 


• No computer required, 100% portable 

• Sleek and compact design 

• Easy to use, one button operation 

• Complies with USB 1.1 specifications 

• Supports both USB 1.1 and USB 2.0 

■ Uses 3 AAA alkaline batteries (not included) 


EASILY GET DATA FROM: 

• Storage Devices • MP3 Players 

‘ Digital Cameras • Card Readers 

• Flash Drives • AND MORE! 


FITS IN YOUR HAND! 


from 


^^acally* j 


iTripmini 


Tfaiismittif 


r 


iMic t! 


SB Its 



The iTrip mini was 
designed exclusively 
for the iPod mini. 


Listen in your car! 

iTrip 


NO BATTERIES NEEDED! 

The iTrip mini only needs a tiny bit 
of power that it gets directly from 
your iPod mini. 

Its form 
matches all 
the curves 
of the iPod 
mini, and 
sounds even 
sweeter! 


a Griffin Technology 



tu 1! 



ONLY 

39’ 


L 




The iMic is a must-have device for people 
who are serious about high quality audio. 

Connect virtually any sound device to 
your iBook, PowerBook, PowerMac or other 
Mac or PC with a USB port. 



from Griffin Technology 


IMic SUPPORTS; 

• Line Level 
Microphones 

• Mic Level 
Microphones 

• Multimedia 
Devices 

• Headsets 

• Communications 
Devices 



_ ^ 
DevDepot ts not responsible for typographic a I errors. Offers subject to change at any time, € 1984’2004 Developer Depot, Inc, Some 
material copyright of their respective holders. All Rights Reserved. Developer Depot, Inc, is a division of Allume Systems, Inc. located 
in California. 
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By Jose R. C. Cruz 


Introduction 

Welcome to ihc dcbiii of Palm On X. This is the 
First of a series of a nicies dedicated to using MacOS X 
as a development platform for PalmOS 1 hope that 
the infonnalion 1 present in these articles would help 
inspire others (including myself) to independently 
provide PalmOS development t(K)ls and utilities that 
take advantage of such MatOS X lechntrlogies such as 
Cocoa, Core Foundalion andXCode. 

Iliese articles are not meant to teach FalinOS 
a]>plicalion tievelopment only, Those wlio want to 
learn PalmOS programming may l->e interested in 
checking out Palm ramming: f’he Demloper's 
Cuide written by Rhodes and McKeehan and 
published by O'Reilly* 

What is a FDB file 

PDB stands for Palm DataBase. It is a binary file 
formal used by the PalmOS as the means to .store data 
on a FDA iiandlield. It is designed to make efficient 
use of limited storage space while supporting a large 
variety of data types, h also allows the storage of 
metadata that is specific to a PalmOS application. 

Structure of a PDB file 

Figure 1 shows die general layout of the PDB file* 
The File itself is subdivided into 5 disiintt data blocks: 
Header, Record List and Record Entry, Application 
Infonnation, Sort Information, and Record Data. 


Hiskl 

Reeoitl 

AppUpitioi^ InJbimatioii 

Sort intbim^tioa 


RECORD DATA 


Figure 1: General layout of the PDB file. 

The Header Blexrk 

llie Header block contains data describing the entire PDB 
File* It storeys the name, version, database auributes, creation and 
iiKKlification dates, type and creator signatures, and offsets to 
any application-sfK'ciric data* 

The basic layout of die Header block is shown in Figure 2* 
listing 1 shou^ die data stmaore tliat defines the block. Ihe 
eleineiiLs dial comprist^ the DatabaseHdrType datatyjK- m: as follows. 

• name, llie name of the file as a 32 character Ostring , 

• attributes. Tlic attributes associated witli the file. 

• version. The version number of the file* 

• creationOate. Date when die file was last created. 
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• modificationDate. Date wlien the file was last modified. 

• lastBackupDate. Date when the file was last backed tip. 

• modificationNumber. 'Ihe modification iD numlier assigned lo 
the file by the PaimOS. 

• appInfolD. The offset of the optional Applnfo data block from 
the beginning of tl^e file. 

• sortInfolD. The offset of Lite < optional Soitinfo data block from 
the beginning of the file. 

• type. The four-character signatLire assigned to the file. 

• creator. The foiij-character signature of the PalmOS 
appiicaEion tluit created die file. 

• uniquelDSeed. The unique ID numlier assigned to the file by 
the PalmOS. 

Tlie date elements are expressed in the nunilx^r of seconds 
since 1970 January T This is tme for PDB files that wem created on 
Palm(!)S 4.x or later Older files may tise a dilTereni reference year 
(1900 or 1904), especially if the files were synchroni 2 ed on a non- 
Windows platform. In eitlier arse, the PDR date values will have to 
be converted .since MacOS X mvs 2001 as its reference year. 

llic attributes element consists of l6 bit-flags. Each flag 
indic'ating iiow the PDB file is to l.ie handled by tlie PalmOS .system. 
Shown in Figure 5 is a barakdown of each l )it fkig and its significance. 



Listing 1. Data structure of DatabaseHdrType. 


struct 

I 

unsigned char 
unsigned short 
unsigned short 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
unsigned long 
I DntahaseHdrTyper 


name[32 ]; 
attributes: 
version; 
creationDate: 
modificationDate; 
lastBackupDate; 

Riod i f icationNuntber; 

applnfolD: 

sortliifoID; 

type: 

creator: 

uniqusIDSeed; 


1« 


L 


hide dataUase 

- open, usij^ oinatir sigmTtile 
-ileletE after clas^ 

- hacicup nqtiized Cnn Bss%|iedcandui^ 


• copy/beani ivtth ciea&u apphratmii 

-RESERVED 

-RESERVED 

- datetoe not closed properly 


L 


lesoiiire ctetahass 

- itadtoniy 

-appUifd bJcck is dirty 

- backup leqvuied (no assigiwd cPiulmO 

“ uistedl if newer (wjHv a different THimB if ppen) 

- reset nequued after 

- do not copy 

- fer file streaming vst 


Figure 3. Attribute bit flags used in the Header block 


The Record List and Entries Blocks 

Located immediately after the Header [>k)ck is tlic Record 
l.ist bl<K:k, Thi.s block conlains tlie numl^er of record entries 
present in the PDB file and the location of the first record entry. 

The basic layouts of the Record T.ist and Entries l}iocks 
are shown in Figure 4. Listing 2 shows the data structure that 
defines the Record List block. The elements that comprises 
the RecordListType datatype are as followsr 


• nextRecordUstlD. Pointer to the next RecordListType stnicture. 
This pointer is updated l^y the PalmOS only when the current 
RecordListType stnicture was unatjle to add more iteias due to 
memory constraiiiLs. The default value is often 0x00000000. 

• numRecords, Tlie numl>er of lecord entries present in the blcx:k. 

• fIrstEntry. 'the upper two bytes of ihe first record entry in t!ie 
PDB file. If tliere are no record entries, this element is 
assigned the value of 0x0000 to preserve a 4-bytes alignment. 




Figure 4. Layout of the Record List and Entries blocks. 
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Listing 2. Data structure of RecordList’lVpe. 

EtnJCT. 

( 

urjRlgrisd longtiextRecordLiEtlD: 
unsigned short numHecords; 
unsigned short flrstEntry: 

1 RecordLlstTypei 

The Recortl Rntry block exists only if the numRecords of the 
Record list block iw a non-zero value. If present, (his blot'k is 
located iinmediately after the Record List block. It is akj 
terminated with 0x0000 after the last record entry to maintain a 
4-byle alignment. 

A non-zem value for niimRecords dcx.^ not always [iiean that 
there are valid rec'cxds present. I’Or peifornruince reasoas, some 
PalmOS applications assign a number of MlllJ. ret'ord entries in 
their PDB files to serve as pkicehofders. It Is often a gtMjd idea to 
valicktte the offsets for each record entry prior to reitding the actual 
ret:ord tbta. 

Each entry in llte Record List entry block is defined by the 
RecordEntryType datatype. Li.sting 5 shows the data stnicturc of 
that cbtatype. The elements that comprise the datatype are as 
follows: 


• localChunklD The ofl'sei of each raw record data from the 
beginning rif the PDB file. 

• attributes. Tfie attributes of each recoal d^ita 

• yniquelD. A three-hyte unique ID number assigned to each 
entry by the PalmOS. 


'Hie attributes element consists o[ 8 bii^nags. Each flag 
indicating how each PDB record data is to txf handled by the 
applitalkm and by the PalmOS system. Figure S shows a 
breakdown of each bit Hag and its significance. 


Listing 3. Data structure of RecordEntryType. 


Etruft 
[ 

unsign€d long iocalChuuklD: 
unsigned char attributes; 
unsigned char unlqueIDt3]: 

1 RecordEntryType; 


7 


0 



RESERVED 
RESERVED 
RESERVED 
RESERVED 
passwDid protection 
mcoRl cunently in me 
aicMve on the next synch 
delete on the next synch 


Figure 5. Attribute bit flags used in the Record Entry block. 


The Application Info Block 

The Application Info or Appinfo block is where a PalmOS 
application can store applicaiion-spccific data. It is also where 
the PalmOS stores category infonnation dial allows users Uj 
group records into different caTegories. Ibis kitrer feature is only 
available if the application ilself supports the PalmOS Category^ 
APIs 

If the PDB file does not have an Appinfo block, the 
appInfolD elcmeni. of ihe Hejider bltx'k will have a 0x00 value. 
However if the application does support tlic Category APIs, its 
PDB file would then have an Appinfo block with the category 
infonmilon located ai the beginning of that block. 

Figure 6 shows die IxLsic layout of the Appinfo block with 
the category .sub-block included. Listing 6 shows die data 
sinuaure of the AppInfoType cbtatype that defines sub-block. 


Oj<00 

nitansd 


0x2S 

cafegpiy [11 

cAfegpiy iitel (^3 ||p| 






Ok 100 

caUgpiylabiirtS] | 

1 IDM 

IDIU j 

0x104 

IDPl 

IDPJ 

IDW 
- - 

tora ^ 




4 


0x110 

IDCW] 

. " !DC13) 

Jut 

RSVD 

0x114 






APPUCATION SPECIFIC DATA 


Figure 6. The category region of the Appinfo block 
listing 6, Data structure of AppInfoType. 

atruet 

I 

unsigned short renamedCategories; 
unsigned char categoryLabele[ 16 ][IbJ; 
ungigned char categoryUniquelDs[ 16 ]; 
unsigned char lastUni<|UelD; 
un s i gtied c har RS VD; 

I AppInfoType: 

The elements that comprise the AppInfoType are as follows 

• renainedCategories. The nuinljcr of caiegtny lalicls renamed 
by tlie user. 

• categoryLabels. An array of 16 category labels. Each label has 
a maximum of 16 characicrs in length 

• categoryUniquelDs. An array of 16 unique ID numlKT 
assigned to eiich caiegory label by the PalmOS. 

• lastUniquelD. The unique ID mimlxfr of the last otegory 
lalx;! diat was used 

Tlic region Ixiween the category sub-block and the next 
data block will contain daui sjKcific U) ihc FalinOS appik:alion. 
It is up to die de\^eloper to define the data structure of tlie 
information stored within that region. Without knowing the 
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exact data siructure, Uic infomialion contained in the 
application-Hix^ciric ^x)rtion of tJie Appinfo block can only be 
viewed as a simple hex clump. 

To determine the size of the a pplioi ion-specific region, J 
use llie following equation: 

= sortlnfolD-applnfolD-sizeoffApplnfoType) 

The preteding etjuation is corrett only if die next data block 
hafipens to be a Sort Info bkxk, If a Sortlnfb block does not 
exists, 1 use the following equation to deiermine tlie size of the 
application-specifit' region in the A[5plnlb block: 

“ f irstReeordEntry - appinf qID - si 7 xof(AppIn foType) 

The Sort Information block 

Tlie Sort Information or Sortlnfo block is another area in the 
FOB file where a PalmOS applic:ation can store application- 
specific data. Like tlie Appinfo bl<x:k, the PDB file will have a 
Sortlnfo block if the SOrtInfolD elemenr in the Header block lias 
a non-zero value* A value of 0x00 would mean the absence of a 
Sortlnfo bl(x:k* However, unlike ilic Appinfo block, the Sortlnfo 
bkx:k is not used at all by the FalmOS (as of this writing). 

The data format of the Sortlnfo block also differs from 
one application to amHhen Without knowing the exact data 
structure, the information contained in the Sortlnfo block can 
only be viewed as a simple hex dump* 

To determine the size of ihc Sortlnfo block, 1 ase the 
following etjuaiion: 

Size^,^„ - f irstRecordEntry- sortInfoID 

The Record Data Block 

'Ilie Record Data block contains all the records stored in tlie 
PDB file. The fbnnat of c-ach record data differs from one 
application to another. Without knowing the exact data staicaire 
of each record, the raw record data can only be viewed a.s a 
simple hex dump. 

The location of each record in the Record Data blot'k ts 
stored in the locaiChunkID element of the Record Entry subdilock. 

To determine the .size of each record, T calculate die difference 
Ixriween die localChunkID of the current record and the 
localChunkID of the next one as follows: 

Size^j^ = f irstRecordEntry - sortInfoID 

However, if I want the size of the last record in the Record Data 
block, I calailate the difference between the size of die endre 
PDB file and die localChunkID of die last record as follows: 

Size,^j = -localChunkID^„, 

Mapping the PDB Data 
Into A Plist File 

ExjKirting the PDB file data into an XML provides a number 
of advantages, the most notable of which are access and 
portability. For example, if I convert a PDB file into an equivalent 


XML file, I can edit the XML iLita using any text ediUir* I can also 
upload the XMl. file to any system (such as Windows, Mac, Unix, 
and so on) with no loss of information. 

Tlte most prevalent XML file format usetl on a MatOS X 
system is the pli*st file* This fonnat uses a key-value system to store 
and ditTcreniiate its data. It ts also relatively easy to generate. Ihb 
Ls die Ibrmiit that I wiD use to export my PDB file data* 

1 defined five major key.s for the plist file. Each key 
represents a data block in the PDB file. To ensure that each 
key name is unique, t use a reverse URL naming scheme 
similar to that used for Java classes. Note that the acronym 
PSRC i.s the ticker symbol lor FahnSource, Inc. 

Listing 7 is tlte XML structure for the com*psrc*pdb*header 
dictionary. This stnicture is a iTKxlified impicmcniaiion of 
DatabaseHdrType (see Listing 1). Nodcc dial 1 gathered all die 
date information under die diclionary key named date, J also 
gathered the appinfo 10, sortInfoID and uniquelDSeed data values 
into a sulMlictionary group trailed ID. 

Listing 7- XML structure of 
com. psrc.pdb.heacler. 

<key>eoTn* psrc, pdb * header< /key> 

<dict> 

<key>n3iiie</key> 

<st r1 ri^></fitring> 

<key>HttrlbjtGa</key> 

<integer>0</intGger> 

<key)versionC/key> 

<inteaer> 0 </iiiteger> 

<key>date</k&y> 

<dlct> 

Ckey)trGatioti</key> 

<datc>Z005-05-18T19i29:44Z</dat6> 

<key>lasiBackup</kGy> 

<date>2D0S 05 18T19:30:037X/date> 
<key>ffiodification</key> 

<date>2005-05-18T19:29:51Z</date> 

C/dict> 

<key>»odlficationNiimbei:</key> 

< lriteger>0</integer> 

<k€y>ID</key> 

<dlc:t> 

<key>applnfo</key> 

<iiiteger>0</integer) 

<key>sortlnfo</key> 

<iiitegsr>0</integer) 

<key>miiqu6Seed</k©y> 

<iiitGgGr>0</integer) 

</dlct> 

<key>type</key> 

Catrin^X/string) 

<key>creator</key> 

<string></string) 

</dict> 


Listing 8 is the XML srrucitire for the 
com.psrc.pdb.record.list dictionary. This structure is a 
siraighiforward implementation of RecordListType (see Lisiing 2). 

Listing 8. XML structure of 
com.psrc.pdb.record*list. 

<key>co]n * ps rc, pdb. rec o rd. 11 Rt< /key) 

<dlct> 

<key>nextRecordList</key> 

<lnteger>0</ltiteger> 

<key >nuiiiRecor d s < / key > 

<iiiteger>D< 7 integer) 
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<key>f IrstKjfitryC/key) 
<iiitG^er>0</ J nt&ger> 
</dict> 


Listing 9 is tlie XML structure uf the com.psrc.pdb.record.entry 
array. Each element in the array is a dictionary wliose slnicturc 
is an XML representxition of Record Entry Type (see Listing 3)* The 
order of cacli dictionary entry is unimportant, I can easily 
recoastuia the original order of eacli record entry in tfie PDB 
tile by simply examining the value stored in the localChunk key. 

Listing 9. XML structure of 
com.psrc.pdb.recorcLentry. 

<key>com.psrc.pdb.record.entry</key> 

Carray> 

<dlcit> 

<key>lD</key> 

<dict> 

<key>localChunk</key> 

<integer>0</integer> 

< key >unique </key> 

<integer> 0 </irLteger> 

</dict> 

<key>attributf!s</key> 

<integer^n</integer^ 

</dict> 

</array> 


Listing 10 is the XML structure of the com.psrc.pdb.Info 
dictionary. This ,stmaure is an amalgam of boih the Appinfd and 
Sortlnfo blocks. The appinfo dictionxtry is a .slraighlftjrwartl 
implementation of AppInfoType (see Listing 6). The categories key 
i,s an array of diciioniiries, exich dictionary containing the values 
stored in the categoryLabel and categoryUniquelD element.s of 
Appinfolype. By combining these values into a dictionary, I am 
able to preserve the one-to-one correspondence between 
category lalx.0 and unique ID. 

Any application-specific data found in the l)kx.L is 

stored using the <datax/data> XMl, tag, 1 also used the same 
appRxicli to store any applic:ation-specific data found in tlie 
Soitlnfb bkx:k. 

Listing 10, XML structure of comp.psrc-pdb.info, 

<key>com,psrc.pdb.info</key) 

<dict> 

<key>appTrifo</k^y> 

<dlct> 

< key >c ategor y RenauiedC / key > 

<icteger>0</integer> 

<key>lastUniqnelDC/key> 

<integer>0</integer) 

<key>categorie^<7key> 

<array) 

<dict> 

<key>id</key> 

<iiitege!:>0</integer) 

<key)Iabel</kay> 

<string></string> 

</diot) 

</array) 

<key>appSpecific</key> 

<data></data> 

</dict> 

<key>sortInfo</key> 

<data>C/data> 

</dict> 


finally, Listing 11 is the XML structure of the 
com.psrc.pdb.record,data army. Like the sortlnfo key, 1 use the 
<datax/data> XML tag to store the raw record data ex ported 
from the FDB file. 

Listing 11, XML structure of 
com,psrc,pdb*record,tlata, 

<key >com * ps rc.pdb.record,data</key) 

<array> 

<data)< /dista) 

<data></data> 

</array) 

Building A PDB Viewer 

I will now show you how to design and develop a simple 
PDB Viewer using CcKoa. I used XCode L5 to develop the 
Cocoa applicalion. My development system is an iBook G3/600 
Mill unit running MacOS X 10.3.9. 

I personally try to avoid u.sing any features that are specific 
to one version of the OS when I design my applications. This 
allows me to maintain some level of cross-platform 
compatiiiilify. It also gives me the freetlom to port my source 
code using other development IDEs such as Metrowerks 
Codewarrior or Project Bulkier. 

iTie Lfser Interface Design 

The III design for the PDB Viewer is quite straight forward. 
I've decided to use a single window to display the information 
retrieved from the PDB file, 1 then use an NSTabView object to 
cremate four panel views. Each panel view i,s dedic'ated to each 
one of the PDB data blocks, Eacli view is also assigned a 
controller that will provide the necessary information to l)e 
displayed. I will talk about the controllers later in this article. 

Since I am developing a data viewer, Eve decided to disallow 
on-screen etiiting. On-screen editing is l>eyond the scope of this 
aiii( k% However, I do plan to awisii the concept in a future article. 

The layout of the Headnr panel view is shown in Figure 7. 
lliis view will display the data contained in the PDB Header 
bl{K‘k. Tile controller assigned to this view is PDRHeader, 
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Free your mind, and design will follow. 


Design the Web 

The Web is no different from any other kind 
of design challenge. Attracting an audience, 
organizing information, communicating 
a message—these are your goals. 
Technicalities are important too, but not 
what you want to worry about every step 
of the way. 

Let Your Creativity Flow 

Most Web design tools—even so-called 
WYSIWYG editors—keep you mired in 
the details of code white you try to design, 
and unless you speak fluent HTML, thafs 


not very helpfuL Aside from stifling the 
creative process, it can make you reluctant 
to make changes—even when you know 
your efforts aren't quite right yet. 

The Better Approach 

Using Freeway, with its intuitive desktop- 
publishing interface, you simply draw 
the page the way you want it to look. 
Freeway’s powerful Master Pages allow 
you to duplicate site elements and keep 
them up to date. Import graphics in almost 
any format or resolution, then scale, 
crop, rotate, and more, and let Freeway 
optimize all of your graphics on the fly! 


Employ rollovers, rich media, and dynamic 
behaviors without hand-writing any code, 
because behind the scenes, Freeway is 
writing technically superb and efficient 
HTML code. 

Viva la Difference! 

We're so sure youll love Freeway Pro and 
Freeway Express that we’ll give you a full, 
unlimited version to use for 30 days, free! 
Once you experience Web design the way 
it should be, you'll never understand why 
you struggled with lesser tools. You may 
even fall in love with design—again. 
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Figure 8 sh<jw,s the Ijiyout of tiie Rocord List panel view. 
Data retrieved from the Record List .suh-biock nre displayed in 
the tliree topmost NSl'extFieid objects. Those retrieved from die 
Record Entry bkxTk are displayed in the NSTableView object. 
'I'he controller assigned to this view is PDBUecList, 



Tile layout of llie Appinfo panel view is shown in Figure 9. 
Integer data retrieved from the eaiegory sub“bkx:k of the 
Appinfo bliKk is displayed in the two NSTextField olijecLs. The 
categoiy luliels and their corresponding unique IDs are 
displayed in the NSTableVicw. Any applii'atton-.specific data 
reatl from the Appinfo block is displayed in the NSTextView at 
the Ixittoni. The controller assigned to this panel is PD13AppJnft>. 



f inally. Figure If) sliows tlie layout of tlie Data panel view. 
Application-specific data read from the Soriinfo hkx'k would lx* 
displayed in the NSTextView at the lx)ttom, Tlie raw record data 
from the PDD ftle wtxuld Ix! displayed in the NtSl'ableView 
together with the corresponding local IDs. 

Two controllers are a.s.signed to update this panel view. 
PDBSoitlnfo handles the Soitlnfo data whereas PDBRecData 


handles the raw record dam. 



The Controllers 

A total of 11 contioUeni comprise^ the PDB Viewer application, 
Tlie five tmtfoUers mentioned in die preceding section maintain the 
display of information in each of the four tab panel views. Three 
cx)ntrDllers are used for data ronnaiting. As for the remaining three, 
one miiinmins a PDB <km buffer, aiiodier liandles file I/O, and the 
last one ctKxdi nates the sigmil traffic between previous 10 
axilrollers. 

For purposes of lengtii, I will only list the eonlents of the 
[leader files of each controller class. To see Ixjth die header and 
source files for each controller class, download the entire XCode 
project of the PDB Viewer from the MacTech well site 
(http://www.mactech.com). 

The Main Controller 

Tlie I^DBMain arnmiiler (Listing 12) uxjrdinates all die .signal 
traffic Ixlwct-T) the oiher controllets in the PDB Viewer application. It 
;dso inteaepts any RIe menu selections and then invoke the 
appmpriate axitrolleis in the approtuiate order. 


Listing 12, The PDBMain controller 
(PDBMain.h). 

§impQTt "PDSFilelO.lC 
^Import *‘PDBHeader*h’" 

//import ”PDBRecLlfSt•h" 

//import ‘’PDBAppInfoJr 
Import '’PUBSortlnfo.h** 

#import “PDBRecData.h" 


iincerface PDBMain i SSObject 
I 

// public instance outlets 

IBOutlet KSTabView ‘pdbPanel: 


I 


TBOutlet PDBFilelO 
TBDiJtlei PDBHeader 
iBOutlet PDBRecList 
IBOutlet PDBAppInfo 
IBOutlet PDBSortInfo 
iBOutlet PDBRecData 


•pdbFiie i 
•pdbKeader: 
‘pdbRecList; 
•pdbAppInfo: 
‘pdbSQrtInfo; 
^pdbRecData: 
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if public action nictliods 
• (IBAction)openDoc: (id) Rendei:; 

- CiBAction)saveDoc;(id)sender; 

// protccccd accessor methods 
(void) updateVdews: 

(void) setPList: 
fiend 

*ro iilLLsirait: ilic role of PDBMain as a iralTic ax^rdimior, \ 
prepared two sigmil diagrams showing die sigrud irafFic during file- 
input and file*<)utput. T used different line colors to help 
differentiate IxMween indqxmdent signal flows. 

Figure 11 is the signal traffic inside die PD13 Viewer when 
the user selects a PDB file to lie viewed by choosing the Open 
PDB menu opcion from die Rle menu. PDBMain receivt'S the 
signal from the Rle menu via its openDcx’ action iiiethcxl. It then 
calls selectinput from PDBFilelO to start the file selection process. 

Once a PDB file has been selected and read, PORFilelO calls 
setBuffer from die PDBBuffer to archive the PDB data. PDBFilelO 
returns control to PDBMain whicfi then calls the updateVtew 
methods of each of the following controllers: PDBHeader: 
FDBKecLLst, POBApfilnfo, FDBSortlnfo, and FDBRecDam. Each of 
these five controllers get their res[>cctive data bloc'ks from 
FDOBuffer via its getBytesAl rnetliods. they then prcx:ess and 
dispby the FDR information in the approprLite 111 ouileLs. 



Figure 11, Signal flow when a PDB file is selected for display. 


Figure 12 Is tlie signal traffic iaside die PDB Viewer when the 
user exports the PDB data into a plisl fde by choosing the Save .plist 
As option trom the Rte itKinu, PDBM;tin receives the signal Ifom the 
Rle menu via its saveDoc method. It then <al!s the setPUst methods 
of die following controllers: FDRHeader, PDBRecList, PDBApplnfo 
and FDBKecDitta. 

These five controllers then enopsulaie their respective data 
blcK’ks as NSDiaionary objeas. Tfiey send their dictionary dejects 
to PDBBuffer via its setPUst:forKey method. Once PDBMain 
regains txintrol, it calls the seleclOutput method of PDBFilelO to 
start the save process. 

PDBFileK^ prompts die user for a plist filename and 
destination directory. It then retrieves the consolidated 
NSDictionary object from PDBFilelO via its getPUst methcxl. 


Finally, PDBFilelO invokes the writeToRle tnediod of the 
NSDictionary object to save its data into a plist fde. 



Data I/O and Buffering 

Tlte Pi:)BFileIO controller (Listing 13) handles all the data 
input and output operations. Hits controller prompts the user for 
die PDB file to l>c viewed. It also prompts the user for a plist file 
name and destination direnory. It reitds tlte PDB data and submits 
it to the PDRBiiffer amtroller for storage. It also t|ueries the 
PDBBuffer for the NSDictionary object to be saved as a plist file. 

listing 13* The PDBFilelO controller 
(PDBFilelO-h), 

^Pimport “PDBBijffer,h" 

// detme the following privato con.stants 
#defitie PDB_nameWitiiKKlcni3ion YES 

^define PDB_tiaiaeOniy NO 

filnierface PDBFilelO : KSObject 
[ 

// public instance outlets 

IBOutlet PDBBuffer *pdbBuffer; 

// prt^icctcil instance properties 

NSString 'srePath; 

I 

// public accessor meiluKls 
- (void) selectinput: 

• (void) selectOutput; 

(NSStrlng *) getNamer(BOOL)witbKxt: 
fiend 

The PDBButTer controller (listing 14) manages the data 
retrieved from a selected l^DB file. Tfie controllers for each tab 
panel relrievc dicir res[xctive data blex'ks ihrcjugh the getBytesAt 
methexJ of die PDBBuffer, 

PDBBuffer also manages an NSDictionary object tliat 
becomes the basis for the plist representation of die PDB data. 
The contrcjilers for each tab panel submit their respective 
NSDictionary objects with the appro[>riate key values to die 
PDBBuffer using the setPlist:forKey methexL The PDBBuffer then 
coa^ilidaies the NSDiaionary objects into a single NSDictionary 
ol>^xt for exportation. 
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listing l4. The PDBBuffer controller 
(PDBBiiffcr.h). 

PDBBijiffer : NSOb’iect 
I 

// |>roLecic^([ instance pnipertics 

NSMutableUata 'dataBuffer; 

NSHiitableDlctionary ■dataDiet i 


// public accessor methods 

- (NSData *) getBuffer: 

^ CHSData *) getDataAl:(unsigned int)offset 
length: (unsigned irit)leTTgTh: 

* (NSDictionary *) getPList; 

- (void) se[.Buffer: (NSData *)filpDate ; 

- (unsigned char *) getBytesAt:(unsigned int)offset 

length:(unsigned int]length: 

- (unsigned int) getBuffcrSlste; 

iI public modifier mctinxis 

‘ (BOOL) setPList:Cid)pdbData forKey:(id)pdbKey: 
@end 


(void) showData; 

- (void) setPList: 

' (NSDate *) adjustOate:(unsigned iong)pdbDate: 

// public accessor metluxLs 

- (unsigned int) getOffset; (PDBBlockTypesJblottk: 

- (BOOL) hasBlock:(PDBBlockTypes)block; 

- (BOOL) getOata: 
dend 

The PDBRecTisi controller (Listing l6) handles the 
processing of data contained in the PDB kec'ord List and Record 
Entry blocks. It displays tlie j)rocessed data in the Record List 
tab panel of the PDB Viewer Since that panel happens to have 
an NSTabieView object the PDBRecList controller also serves as 
die table's data source. Finally, the coni roller populates the First 
Record Entry field if and only if there is ai least one valid record 
in the PDB file. 

Listing l6. The PDBRecList controller 
(PDBRecUst.h). 


Displaying PDB Information 

As meniioned previously, there are 5 controllers that handle 
the display of data for each Lab panel view, 'fhese controllers 
obtain iheir respective data bkxrk l^y cjiierying PDBBuher. These 
controllers aLsti encapsulate their data as NSDittionary objects. 
'Hiey then vsend llieir NSDiciionary^ objects to PDBlkiiTer to Ixi 
a)nsr)licbited for exportation. 

The PDBHeader controller (Listing 15) handles the 
processing of data contained in the PDB header [)lock. It 
displays the processed data in the Header tab panel of the 
PDB Viewen The controller also calculates the time offsets 
needed to correctly display the PDB file's creation, 
modification and la.sl-backup dates. This correction is 
necessary l>ecause to the different reference years used by the 
PalmOS and MacOS X. 

Listing 15. The PDBHeader controller 
(PDBHeadenh). 

(fimport *PUB.b" 

^Import "PDBBuffer.h** 

^import ‘•PDBFormatSig.h" 


iJ^iroport "PDB.ir 

\\ 1 mpo r t " PDBfluf f e r . h ** 

(/import “PBBFormatHex.h” 

6?iuterface: PDBRecList : MSObjeet 

t 

// protected instance outlets 

iBOutl^t PDBBuffer ‘dataSource: 
iBOutlet FDBForraatHex 'dataFormat; 

TBOutlei NSTextField *fieldlDLocal: 
IBOutlet NSTextField *fleldRecordCount; 
IBOutlet MSTextField •fieldRecordFlrst: 
IBOutlet NSTableView ‘tableEntries; 

// protected instance pmjierlieii 
NSData *dat^Buffer: 

NSHutableAiray ' dataRecords: 
RecordListType *dataPointer; 

I 

// public niodtfier methods 
(void) updateVi^w; 

(void) showRecordList; 

// piililic accessor methods; 

(BOOL) hasEtitrieu; 

- (BOOL) hasRecords; 

- (BOOL) gfJtReCDrdLlst: 

- (BOOL) getRecordETitriea; 


^interface PDBHeader : KSObject 
( 

// protected instance outleis 
IBOutlet PDBBufftyr *dataSource: 

IBOutlet PDEFormatSig 'dataFormat: 


- (uDfilgued int) recordCount: 

- (unsigned Int) f irstRceord: 

(unsigned Int) getRecordAtIndex-(unsigned int)index; 
(vDid) setPList: 

<i?end 


IBOutlet NSTextField 
IBOutlet NSTextField 
IBOutlet NSTextField 
IBOutlet NSTextField 
IBOutlet NSTextrield 
IBOutlet NSTcxtField 
IBOutlet NSTextField 
IBOutlet KSTextFieid 
IBOutlet NSTextField 
IBOutlet NSTextField 
IBOutlet NSTextField 
IBOurlet NSTextField 


*fieldAttrlbutea: 
•fleldOateBackup: 

* rieldDateCreate: 
•fieldDateModified 
‘fieldIDAppInfu; 
•fieldIDModifled; 

* fieldIDSor11 nfo; 

* fieldIDUnique: 
*fieldNaine; 
•fieldSigCreator; 

* fleldSigType: 
‘^fieldVersion: 


// protected mstance property 

NSData •dataBuiIfer; 

Da taba seHd rType •dntaFoiut e r; 


// public modifier methods 
" (void) updateView; 


The PDBApplnfo controller (Listing 17) handles the 
processing of data contained in the Appinfo block. Ir 
displays the processed tlata in the Appinfo tab panel of die 
PDB Viewer. Like the PDBRecList controller, it serves as a 
data source for the NSTableView object in the Appinfo panel. 
'I'he controller also locates any application-specific data 
contained in the Apfjlnfo data Ivlock. If found, the controller 
then displays the application-specific data In the appropriate 
NSTextView objecl using the PDBFormatDaLa control ler to 
reformat the data. 

It should be noted tliat die PDBApplnfo controller only 
perft>[ms its ditta process if and only if the PDli data does 
include an Applnft> block. 
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Listing 17. The PDBApplnfo controller 
(PDBAppInfoJi). 

Import "l-DB.h” 
fimport "PDEBuffer.h" 
fonport "PDBHerider .h** 

#import "PDBRecLlst .h" 
tf’import ""PDEFonnatOata^h" 

//^import **PDBSortlnfo.b** 

^Interface PDBApplnfo ; iJSObject 
i 

// protected instance outlets 

IKOutlet PDBBuffer *dataSource; 

XHOutlot PDBBeader ‘dataHeaderr 

IBOutlet PDBRecMst 'dataRecList: 

iBOutlet PDBForfnatData ^dataStteajn: 

IBOutlet PDBSortlnfcs *dataSortInfo j 

IBOutlet NSTextView *fieldAppTnfoj 
IBOutlet NSTextField *fieldLasLUniqueTn: 

IBOutlet NSTextField "fieldRenaniedCoimr: 

IBOutlet NSTextFiald *fieldDataiength; 

IBOutlet NSTableView *tableCateaorits: 

// protected instance pnipertics 

NSData ^dutaBuf fffr , MataSpecific: 

AppInfoType MataPulnter; 

I 

// public modifier methods 

(void) updateView: 

(void) fjhowDatalnfo; 

- (void) showDataSpecific: 

- (void) lietPList; 

// public actesstir nicthod.s 

- CBOOL) getOataInfo: 

- (BOOL) getOataSpeclfle: 

Tiic PDBSortItlfo (Listing 18 ) controller handles liic processing 
of data contained in the Scirtlnfo hIfK’k. It displays the protressed 
dita in the NSTextView olijcct located in the Data lab panel of die 
PDH Viewer. like die PDBApplnfo controller, it only pcrfoniis its 
data process if and only if the PDB tkiUi docs include a Sortinfo 
bloc'k. 'Ilie controller als<) makes use of the PDBFormutDala 
controller to refomiat the data in humxin-readable fonir 

Luting 18. The PDBSortInfo controller 
(PDBSortlnfo.h)- 

^import 

ffimport "FDflBufEer^b** 
jimporr “PDBHeader.h" 

^import "PDBRecList.h" 
jLimpart ^PDSFotmatData. b** 

^iniE^rfaco PDBSortInfo : NSObject 

f 

// protected instance outlets 

IBUuileL PBBBuffer *dataSourcer 

IBOutlet PDBEeader 'dataKeader; 

IBOutlet PBBRecList 'dataRecList: 

IBOutlet PDEFormBtHata *dataStraam: 

IBOutlet NSTextView 'fleldSortTnfo; 

IBOutlet NSTeKtField 'fieldDataLengthi 

U protected instance properties 

NSData •dataBuffec; 

I 

// public mixiirier mcthixls 

- (void) updateVlGW^ 

// public iiccesfw>r melhtKLs 
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- (BOOL) getData; 

- (NSData *) getSortlnfo: 

@€nd 

The PDBKecData controller (Listing 19) liaiKlles the 
prtKessing of any existing raw record data contained in rhe PDB 
file, li determinc^s ilie kxation and length of each raw record using 
the infonnation provided by rhe PDBRecLLst controllen It then 
jxirses out the^e rea)rds and displays them in the NS^l able View 
object Icx'jiied f)n the Data panel of the PDB Viewer. 

Listing 19- The PDBRccData controller 
(PDBRecData. h) 

//import ‘'PDB.h" 

Import "PDBBuffer-h" 

^Import "PDBRecList,h” 

^iaipurt ■■PDBFormatRex.h’' 

^import "PDBFortnatData-h” 

^interface FDBRecDaia : NSObject 
I 

// protcaed instance oiiikis 

IBOutlet PDDBuffer 'diitaSource; 

IBOutlet PDBRecList *dataRecList: 

IBOutlet PDBFomatHex 'dataForitiat: 

IBOutlet PDBFormatData MataStteam; 

IBOutlet NSTableView ’tableRecotds: 

// protected instance im>|xnics 

NSMutableArray ’dataRecords: 

\ 

if public modifier mcthtKls 
(void) updateVlev: 

(void) aetPLiat: 

// public accessor methods 
(BOOL) getDataj 
tend 

Data Formatting 

lliere are tlirce controllers subclassed from the NSFonimitcr 
objecL. First of tliese is BOBFormatSig (Usting 20). This 
controller takes the original integer values of the type and 
creator signatures of die PDU file and converts them into die 
familiar four-character signatures. 

Two of the NSTextFields in die Header tub panel uses 
PDBFormatSig as dieir forinatter. FDBHeader also uses 
PDBForrnatSig to format the type/creator signatures when 
preparing the PDB header data for oulput to a plist file. 

Listing 20. The PDBFormatSig controller 
(PDBFormatSig-h) 

#int0^rfacfl POBFomaatSig I NSFormatter 

I 

1 

// public modifier methods 

- (NSStiring V) lrLt2fli Cunsigned int)intArg; 

@end 

Ihe second cxmlroller, PDBFomiatllex (Listing 21), takes an 
unsigned integer value and generates the corrcsfionding 
hexadecimal string. 

Three NSTextFields in the Data lab panel use 
PDBFormatHex as their formatter, lliese three fields display die 


Disseoing The PDB Fill 37 






Littril^utes, Applnfo and Son Info IDs srored in the PDB header 
b)(K'k. The NS'lextField used to display die ncxtRecondlD value 
in die Record List tab panel also uses PDBronnutHex as its 
fortiiatter Finally, die NSTableViews in both the Record List and 
Data tab panels use PDBFomiatHex lo format the values 
displayed in their Local ID columns. 

Listing 21 , The PDBFormatHex controller 
( PDBForinatHex,h) 

^interface PDBForinatHex : NSFortnatter 

I 

I 

// public modifier methods 

- (NSString *) int2>iex: tunsigned intJintArg; 

Tile third controller, PDBFormatData (Listing 22), takes an 
NSData object and converts raeh liyte value into some liuman- 
readalile form. A byte value of 0x00 is represenTed by a bullet 
(•). Byte values within the range of 0x20 and 0x7e are 
represented by ihdr cciuivalent ASCII character. Any other byte 
values are represented by an ellipsis J. 

The PDBFormatD^Ua Is used Iiy the f^DBApplnftr and 
PDBSortlnfo contmllers lo hirmat any application-specific data 
prior lo being displayed in their respective NS'lextViews, 
PDBRccData controller also uses PDBFomiatDaia lo format any 
raw record data prior to Ix^ing displayed in tile Record Data 
column of the NbTableView object. 


Listing 22. The PDBFormatData controller 
(PDBFormatData.h) 

^interface PDBForiria tData ; NSFormatter 
[ 

1 

// public modiOcr iricihixls 

- (NSString *3data2streain: (NSData *)dataArg; 

Send 

Possible Improvements 

For the purposes of this article, the PDB Viewer only 
allows me to load and view the data contained inside a PDB 
File as well as export it to a plist file. There are however, a 
nuini)er of directions I can pursue dial would further improve 
upon the application's usability. Some of the more notable 
ones are as follows: 

* Add the ability lo load and view a plist file containing PDB 
data and generate a PDB file fiom the data read. To 
at:compU.sh this, PDBFilelO needs to correctly recogniTie 
tltat the data being read is coming from a plist file. 
PDBBuflFer will then separate the ebta into individual blocbs 
(Header, Record List, etc..) and sUire each bk^k as an 
NSDictionaiy entry. Then POBHeader and its kind will then 
asks for their resfx-'ciive data blcx^ks to be parsed and 
displayed accordingly. 
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* Use a hex-editor style IJT to display any appiieaticjn-specific 
ctira from Lite Applnfo and Sonlnfo diiui blocks. One way lo 
accoinplisli thus Is to subtrlass NSTableView, Ibe subckLvs (let’s 
call it PDBHexIahie) would cottsist ol' 18 coitifnas: t>nc for tlie 
data offsets, one for the ASCII stream and the re.st for the 
hexadecimal values. Also, a contniHer (PDBllexShow) would 
lx* designed to handle the display of data in the PDBHexTable. 

* Allow on-screen editing of PDB data and then Siive the 
edited data back inlt> a nseparate PDB or plist file. The 
controllers for each of the tab panel views (such as 
PDHHeader) will have to be mexiified to suppon this feature. 
Also, Id^BlulelO will have to be modified to allow^ users to 
select the type of file into which the data would Ite saved 

Summary 

1 have shown you the basic structure of a PDB file and 
how information is stored in that file. 1 have also 
demoastrated how to use XCode and Cocoa to build a basic 
PDB Viewer lliat allows us to view the contents of a PDB file. 

I was also able to atld an additional feature to the PDB 
Viewer thus allowing me to export the PDB data into a piist 
file for later viewing and perhaps even editing. 

Once again, the complete XCode project for the PDB 
Viewer is available for downloading at the MacTech website 
(www.mactechxom), 

In my next article, I will cover tlie liasic staicture of a Palm 
Resource file (or PRC). Teaming the data staicture of tlie PRC file 
is an important step towards learning PalmOS development as 
this is the universal executable fomial used by a PalmOS 
application. I will .show how to develop a PRC Viewer that 
would allow me to view the contents of a PRC fde as well as 
save the PRC daui into a plisr file for later viewing/editing. In 
addition, I will also shf)W tiow to allow the PHC Viewer to load 
the contents of a piist file (which contains PRC data) and then 
recreate a PRC file. 
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Website Not Found By Clients 
HTTP 404 - Website not found 


The website you are looking for can’t be found 
by your clients. It may have been improperly 
marketed, had poor design, or didn't work. 
Regardless, it’s not helping your business! 


Your Options: 

• Rent a chicken suit and stand on the 
corner handing out flyers 

• Paint the company URL on your chest and 
face during a major sporting event 

• Contact SharpNET Solutions internet 
marketing and web design specialists, 
watch your traffic and rankings increase, 
get great feedback from all your 

new customers. 

HTTP 404 - Website needs SharpNET 


. 



Not Marketing Your Site? 

If you are not marketing your 
website online, you may as well 
have a 404 error for a website. 

Web Design 
Internet Marketing 
Consulting 
Lead Generation 
Multi-Media 

1 - 877 - 583-8396 

www.sharpnetsolutions.com 
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Building An AppleScript- 
Based Automator Action 


T here has been a lot of excitement in the developer 
community around the release of Mac OS X 10.4. Unique 
technologies like Automator, Dashboard, and Spotlight are 
providing new opportunities for Mac developers to build 
unique tools that appeal to users everywhere. This month, we 
are going to walk through the process of developing for one of 
these great new technologies, Automator. 


Aulom:itor is Apple’s new iechnc)lo|ry 
ihut is helping' users everywhere to begin 
auUiniating re|X:titive and lime consuming 
tasks in I heir own unique workflows, 
allowing llieiii lo become more efficient. By 
placing actions, whicli are single automated 
lasks, Togetlier in a sequence, users are able 
to construa a fully automated woridlow, 
without the need to write a single line of 
code. How does this help us, as developers, 
you may lx.* asking? Well, someone needs to 
create the aaiuns ilial give users this pxwer. 

Auromator actions are buill in Xcode, 
and are typically developed using eiilier 
Objective-C, AppleSc ript, or a combination 
of these, and possibly oifier languages. 
Objectivc-C may he used to develop 
actions liiai interact with core components 
of the OS, or applications with a public API 
AppleScripi may lx? used to develop actions 
that interact wiih any scTiptable application 
or process on the Mac. 

In this article, we will walk tlmiugh the 
process of cteaiing a basic Automator action 
with AppleScTipl. This ftrief overview should 
pix)vide you with a basic understanding of the 
primary’ steps involved in cteating a simple 
AppleScTipt-based aition. Once you 
understand the Ixisic concepts of building an 
action, then ycxi can take additkjnal steps on 
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your own to Ixgin exfKinding yrxir knowledge llmjugli additional 
resources. Before long, you will be creating complex actitms tliat 
interact with a variety of saiptalile ap]>licaiions or piocesses, and 
sharing lliose actions with users. Obviously, it should g(j wiihait 
siiytng tliiit you will need Mac OS X KU and Xcode 2 or higher to 
create an Auromator aciion. 

Getting Started 

Tliere are a numlxr of steps involved in the ertration of an 
AppleScript-based Aulomator action, and we will move tlm>ugh 
the t^nxess fairly quickly, 

Tlie fiiM stq> in cirating an aaioii is to detennine what the action 
will do, IVe done tills putt for you already, CXir action will accept a 
list of values as input, and tlien display a choose from list dialog to the 
user, allowing the user to make a .selection. '11 le value specified by 
tlie user will tlien lx [xissed as output on to die next action in an 
AuioiTKUor w'orkflow sequence. An aciion such as diLs might lx? used 
to give a teser ilie opjxiitiitiity to process only a specified set of data 
during execution of a workflow. 

The choose from list comiiiaiid is found in the User 
Interaciion suite in the Standard Additions scripting 
addition»included with Mac OS X. 

Create an Action Project 

Once you have deieonined wtiai your action wiD do, the next 
step is to create a new Xcode project. To do this, launch Xcode 
and select New Project.., from the fde menu. You will liien lx* 
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prompted to selea fiponi n list of pa**existmg propcx iemplatc^s. 
Apple has included a handful of Automator acti^m templates witli 
Xccxle to get you started. Select the Appk\ScnfilAutomatorAction 
tem[ilalcs and click the !Vext button to proceed. See llgure L 
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Figure K Choosing an Automator Action Project Template 


[f you are feeling adventurous, or if you prefer 
developing in ^>ther languages, be sure to check out the 
Cocoa Aiitomuior Action and Shell Script Autonialor 
Action (Xcode 2.1 or higher) templates, also included 
with Xcode. Also, be sure to check out t!ie example 
Automator action projects, cntn|>lete with .sample ccxie, 
loaited in the Developer > Examples > Automator folder. 


Next, specify a name for your Automator action, in this c'ase, 
Choose List Iteitis. Specify a directory for the project, and click 
the finish buiton to create the action project. See figure 2. 

■ 0^0 __ Asti$tant _ j 

New AppleScript Automator Action 


Project Nime: ' Chcw« lilt Ittmj ^ 

Project Dtreciofv -/Desktop/Choose lift kems/ Q ( dmst.,. ) 

The project director^ -/Desktop/ClKHne list Rents/ svli tH crtiuid (f neccisAnr, «id the 
Hh ChoM* Ust l»rns.JKod4proi wtll iw crvAied ih*reJn. 


f CaiKd~) f PrewotfS ^ 

_ A 


Figure 2. Specifying a Project Name and Directory 


You should now have an Automator action pri^jeci opened 
in front of you in Xcode. See figure 3- If you are new to Xcrxle, 
then tile project may ftxik a little overwhelming to you at first 
glance. However, tliere are really only a handful of components 
with which we, as AppleScript devek>pers. will need to interact. 
These components are: 

mairiMppiescripl - This is your action's main AppleScript file. It 
will contain the AppleScript code that will trigger when the 
action is run in an Automator workflow, 

maittnih - Tliis is your action's interface, as it will be displayed 
wiien the action is placed into the workflow view in 
AuTomaror's interface. 

info.plisl - This is essentially a configuration file. It will indicate 
how your aaion .sliould lx- handled within Automator, and 
within a workflow secjuence. 

An English instance of an InfoPiist.strings file is also 
present, and may be used to specify English 
translations of properties contained within the 
infripiist file. Optionally, additional versions of this 
file may be added for additional translations. Tor this 
sample action, we will not use tJic InfoFlisUtrings 
file. 


We will discuss each of these comfKments in greater detail 
as we Ixild our action project. 



Figure 3. A New AppleScript-Based Automator Action Project 


Update the Action’s Properties 

Once we liave created our action project, we need to make 
some adjusttiients to the inpiplist file within the action projea. 
As previously mentioned, the irtfbplist file is an XML file, wliich 
provides infonnation about the action to the Automait>r 
application. Tliere are a numlxr of properties and values 
included in the infoplist file. For tlie purpo.ses of the action we 
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are buildmi', we will discuas only a handful. At this time, take 
ore not to make chunges to any properties included in liiis file, 
w I rich are not specified below. 

There are a number of ways that you can ixUl an action's 
infOrpiist file. For this project, we will edit the file's XML ct)de 
directly. Click on the in/o.pihi file in your aaion's project to 
view the file’s contents within your Xccxle window. Skim the 
infoptist file, paying special atfention to the prof^cnies listed 
below, and making any adjustments indicated 

AMAccepts 

Til is property provides Auiomaior with information about 
die input that an action will accept Tliis property contains an 
XML dictionary, which specifies whether the input for the action 
is optional, and which types of input are acceptable, [f an 
action is configured to accept a certain type of input, tlien 
Automator will generate an error if an incompaiil)lL‘ input type 
i.s passed to the action. 

An action may be configLired to accept multiple input types, 
if desired, and each in pur type must be sfx.‘cified as a unwersal 
type identifier (UTl). A list of valid UiTs is included with die 
Automator develof^er docunientaiion. For our action, we will 
sSimply make use of the default CTl hir this property, 
com.apple.applescript.object, which indicates a generic 
AppleScript object. Beaiu.se this is t:onfigured by default, you 
should not need to modify any aspects of diis property. The 
pro]'>erty should apfx:ar as Follows within your mfoplisl file: 

< k^y > AHA cce pt g </key > 
edict) 

<key>Con tainerC/key) 

<aLrlijg)List<7string> 

<key>Optional</key> 

<false/> 

< key>Types</key) 

Carray) 

<string>codi.apple.applescrlpt.object</siring> 

</array> 

< 7 diet) 

AMApplication 

Tins property specifies the category in which the action will 
apjx-ar in die Librar^^ list within Automator’s interface. For our 
anion, set this projK^rty to a value of Automator. This will cause 
the action to appear within the Automator category. 

<kQy>AMAptjlication</key> 

<strlrig>Autom 3 tor</strinB> 

AMCanShowSeiectedltenisWhcnRun and 
AMCanShowWhenRun 

These properties indicate whether the u.ser sfiould lx: 
allowed to configure the action's interface to Ixf displayed when 
run within a workflow. For our aaion, set the values of both of 
these propertie.s to false, as we do not want die user to liave die 
ability to display the action's interface during processing. 

<kcy ) AHCanShoVfSel ected IteJimWhenRun^ / key ) 

<falge/> 

<key ) AMCanSbowtfhenRtin< / key) 

<false/> 


AMCategojy 

This property is u.sed to help Automator group similar 
actions togedier, internally. Currendy, the value of this 
property is utilized by Automator only when die user performs 
a search via the search field in Aulomator’s t(X)!bar. For our 
acaion, set this property's value to Dialog. 

<key>AMCategory</key) 

<string)Dialog</string) 

AMDefaultParameters 

This properly i.s used to link attributes of our action's 
interface to the action's code. We will revisit this properly 
shortly, once we have created our action's interhice, and we will 
specify iLs value at that time. 

AMDcscription 

This property contains an XML dictionary, which contains 
the information tliat Automator displays in die description area 
when the action is selected. This value may be used to specify 
a variety of different types of information. For our action, we 
will use only a few. Configure diis property in your action's 
infopiist file to mutch the following: 

<key)AKOescriptlon<7key> 

(diet) 

<k€y >AHD T n p u t </key) 

<strlng)A list of values, whicb mfiy be coerced to text 
formet</string) 

<key>AMriOpt ions </key) 

<string)Allow niultiple selections; allow empty 
selections</string) 

Ckey)AMDEeaultV key) 

<string>Speclfled list itemsC/string) 

<key >AMT] S umma r y < / k e y> 

<strlng>Thls action will ptompr the user to select 
from a list of values .</string) 

</dict> 

AMIconNamc 

This prf>pefTy is used to SjX'cify the name of a graphic file 
that will serve as die action's icon in Automalor's Action iisi, as 
well as in the action's descriphon, when the action is selected. 
You may spet'ify the name of a graphic file witliin your project, 
within Automaior's bundle, or within the “CoreTypes’' bundle 
(found in System > Libmrjf > CoreSennees), Ft)r our action, we 
will specify a gnipiiic that is included wiihin Automator's 
bundle, a standard AppIeScripl icon: 

C ke y > AH I c onfJa m e < / k ey > 

<String>AppleScriptLarge</string) 

AMKeywords 

'Hiis property is used to sjxcify keyw^ords for an aaion. 
These keywords will lie accessed by Automator wlien a user 
performs a seardi via tlie search field in Automator's tool[)ar. 
?or our action, we will s(>eciry select and display as keywords. 
Fee! free to assign other keyw'ords as well, if you would like. 

< key> AHK e ywo rd s </key) 

<array> 

<stiriiig>select</string> 

CBttlng>dleplay</atrlng) 

</array) 
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AMName 

This properly contains the name of your action, as it will 
appear in list within Automator* Ihis property should 

already be populated for you, [)ul it still bears mentioning. It 
should appear as follows within your action's file. 

ey ^ AMN atiie < / key 

<string>Choose List Iteciis</string) 

AMProvides 

'lliis property is similar to the AM Accepts property. It 
contains an XML dictionary, and indicates Lite type of output that 
the action will provide to the next action in a workflow 
sequence. Like tiie AMAccepts property, the OLitput type must 
be a valid LJTl. By default, diis prt>perty should akeady lie 
configured to output a generic AppleScript ohicci, so you should 
not need to adjust it. This property should appear as follows 
within your action's info.plisi file. 

<key>AMProvides</key> 

<dict> 

<key>Contalner</key^ 

<sti:lng>Llst</s t rlng> 

<key>Types</key> 

<array> 

<string>com*apple .applescript *Dbjec t</stritig> 

</array> 

</dict> 

Localized Strings 

As previously mentioned, ytai may use an hifoPHsLstrhigs file 
to sparify kx:ali2ed versions of strings wiiliin your action’s infaplist 
file. Ht)wcver, for the purpexses of tliis example uciitm, we will noi 
perform this task. Tlieiefore, click on the InfoHislstnngs file in 
your action project, displaying its conienis in Xctxle. Next, delete 
the existing text fmm this file, leaving tlie In/oPiMslfin^ts file blank. 

Build the Action’s Interface 

The next step in building our Automator action is to create our 
action’s interface. First, doyl>le click on the fnain.nib file in your 
action project to open file action’s nil5 within Interface Builder. 
Once opened, double click t)n the nib’s view instance, if it is not 
already dispLayed for you. 

Assuming that you already liave a basic understanding of how 
to use Interface Builder, then you may begin adding interface 
elements ro your action's view. For our action, add two 
checklx)xes, set their size to small, and title them AUow Multipie 
Selections and Alkni^ Emptyf Selections, as shown in figure 4. 
These checkboxes will lx* the .settings within our action's interface, 
whicli the user will be able to configure from within Aulomator 



Figure 4 Editing an Action's Interface 


For more complex actions, you may add additional 
interface elements. However, be sure to adhere to 
Apple's Aqua human interface design guidelines, mking 
into account the limited amount of space within 
Automator's interface. 

Bind The Interface to the Action’s 
Code 

Once an action's interface has been designed, the 
interface elements must be linked to the action's code. This 
will allow the action to detect changes made to the action's 
settings by the user, and trigger the appropriate processing 
code* 

'Ihere are multiple ways of linking interface elements to the 
axJc of an action* However, the most straiglilftirward is ro 
make use of Coma hm4lng$. lliis is the metliod tliat we will 
use for our action. Tlie fisllowing steps will walk you tlirough 
the prex'ess of creating these bindings* 

Create Parameter Keys 

The first step in binding interface elements to aaion code 
is to assign parameters* lliese parameters wdll later be attached 
to utirihuies of the interface elements, and inserted into our 
action's code. By doing this, changes made to the specified 
inlerface element attributes will automatically synchronize to the 
ctkIc of our aciion. Begin by clicking the Fttrameler^ instance 
in the action’s nib. See figure 5, 



Figure S. Selecting the Parameters Instance 


Next, type command + /* 't his will open the Inspector 
panel, if not already opened, and display the Attributes 
pane for the selected Paramelers instance. Next, click the 
Add button in the Attributes pane of the Inspector panel, 
and add two keys. As ihe new keys arc created, double 
click on each of tliem, and re-name them 
allowEmptySelection and allowMutUpieSelections, as 
shown in figure 6* 
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Figure 6. Interface Parameter Keys 
Bind Parameter Keys to Interface Elements 

Once you have created parameter keys, select each of the 
checkl)oxes in the action’s window view\ and perforin the 
following steps. Type command + 4 to display the Bindings 
pane in the Inspector panel for the current checkbox. Click on 
value in the Bindings panes of the Inspector panel, and select 
the parameter key that corresponds to the current checkbox in 
the Model Key Path field. See figure 7 for an example of a 
properly configured parameter binding for the Allow Multiple 
Selections checkbox. 



Figure 7. Binding Parameter Keys to 
Interface Element Attributes 


Once parameter keys have been bound to the values of 
both checkboxes, save the action’s interface in Interface Builder, 
and return to Xcode. 

Specify Parameters in the info.plist File 

Now that we have configured the bindings within our 
action’s interface, we need to link them to our code, so that they 
will synchronize automatically when modified by the user. Click 
on the info.plist file again to display the list of properties for the 
action. Now, we will revisit the AMDefaultParameters property, 
which we mentioned briefly. 

The AMDefaultParameters property should contain an XML 
dictionary, containing key/value combinations for the various 
parameter keys specified within your action’s interface. Values 
specified for these keys will serve as default values for any 
bound interface elements. For our action, set the 
AMDefaultParameters property to contain a key for each of the 
parameter keys that we specified, along with a value of false for 
each, 'fhe properly configured property should appear as 
follows within your action’s info.plist file: 

<key>AMDefaultParameters</key> 

<dict> 

<key>allowMultipleSelections</key> 

<false/> 

<key>allowEi!iptySelection</key> 

<false/> 

</dict> 

Write the Action’s Code 

Next, we are finally ready to begin writing the processing 
code for our action. We will be doing this entirely with 
AppleScript. Click on the main.applescript file to display the 
action’s AppleScript code within Xcode. Next, specify the 
following code for the action: 

on run {input, parameters} 

if (class of Input) is not equal to list then set 
input to (input) 

if input = {] then return input 
set inputStrings to {1 

repeat with a from 1 to length of input 

set end of inputStrings to item a of input as string 
end repeat 

set allowMultipleSeTections to 
IallowMultipleSelectionsI of parameters 

set allowEmptySelection to |allowEmptySelection| of 
parameters 

set outputStrings to choose from list inputStrings 
multiple selections allowed allowMultipleSelections empty 
selection allowed allowEmptySelection 

if outputStrings = false then error number -128 

set output to I) 

repeat with a from 1 to length of inputStrings 

if outputStrings contains (item a of inputStrings) 
then set end of output to item a of input 
end repeat 

return output 
end run 

As you write processing code for an action, take care to add 
protection for scenarios that might cause the action to generate 
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an error (luring processing. F(jr example, our acii<jn expects a 
list of values to l^e provi(Jed as input, llierefore, I liave added 
code to ensure tliat die specified value is a list, coercing it to a 
list if necessary. 

Test the Action 

Once liic action’s processing ctxlc lias lieen written, you are 
ready to liegin testing your action. You may do so by selecting 
Build and Run frrjm the Build menu within Xcxxle. E)oing so will 
launch a lempomry instance of die AuLomaLor appliaiUon, and your 
action sliould be accessible for testing> 

To test our specific action, constmct a sample workflow. 
This workflow may consist of a Run AppleScript action, our 
Choose List Items action, and a View Results action. Sec 
figure 8. 



If all goes well, your action .should display a list of passed 
input values when run within a workflow, and ourpui the 
user-specified values. Inevitably, you may make a mistake, 
which could prevent your action from appearing within 
Auimriaior, or from running properly wiihin a workflow 
sequence. It happens to the best of us. To lielp resolve any 
issues that may occur during development of this action, you 
may download and consuli the .source code for this example 
action from the following URL; 

<http://wvwv.automatedworkflows.conn7file5/demos/MacTE 

CH. 08 . 05 .Example. 2 ip>. 


In Closing 

This article should serve as an initial guide to gel you 
starred with building your own AppleScript-based Aiitomator 
actions. However, it is not meant to serve as a definitive 
guide to Automator development by any stretch of tlie 
imagination. For detailed information about creating 
Automator actions in AppleScript, as well as Objective-C, 
please refer to the developer documentation included willi 
Xcode, and also available online via the Apple Developer 
Connection, 

If you prefer a book on Automatfir, then be sure to 
check out my comprehensive Mac OS X Technology Guide 
to Atitomator^ available from SpiderWorks 
http://www.spiderworks.com in both print and eBook 
formats. The first section of the book covers using 
Automator, and the second section covers developing your 
own custom actions. If you think that you need a refresher 
on AppleScript itself, be sure to check out Danny 
Goodman's AppieScript Ilandhook wdiile you're there as 
well. Sample chapters of both hooks are available for 
download. 

Until next time, keep scripting! 

_ ^ 
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PATCH PANEL • by John C. Welch 


Mac os X Server 10.4 




Part Two Of Our Overview Oi 
Mac os X 10.4 Server 

F 

■ ast time, we took a tong look at Mac OS X 10.4 Server from 
■_ the Server Admin point of view, and concentrated mainly on 
server setup, features, and some management. Now, we’re 
going to look at Mac OS X 10.4 Server from the Workgroup 
Manager point of view, or the tools and new features that Mac OS 

X 10.4 Server provides so you can better manage your network. 


Workgroup Manager 

Workgroup Manager is the Tool you 
use lo manage your overall Mac OS X 
network. Where Server Admin works wiili 
one server at a time, and only servers, 
Workgroup Manager works with multiple 
servers, dieni tmcliines and tlicFil users. 
It‘s the primary tool for' 

• Setting sharepoints and access 
policies for those sharepoints 

■ Setting client machines and client 
iniichine groujis, their atxcss 
policies and preferences 

• Setting asers and user groups, their 
acces.s policies and preferences 

• Manual manipulation of 0|>cn 
Directory data 

WorkgroLtp Manager Ls also the way 
you handle directory data from multiple 
directory systems. If you have multiple 
systems defined via the Directory Atx:e,ss 
application, then Workgroup Manager can 
work with those systems. 
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Directory Access in Mac OS X TOAi 


One imponant point here is that you don’t have to run 
Workgroup Manager on the server your using it with. You can 
also mil Directory Access against a remote Mac OS X Server box 
via the cmd-K option, and this allow,s for wliat is called 
“direttory mode’’, accessed via the “View Directortes” option, or 
cmd-D in Wt>rkgroup Manager In direc:tnry mode, you nm 
Wtirkgroup Manager from a remote adminisiraiion Mac, that c'an 
be IxHind, via Directory Access to different directory systems 
llian the server you're managing. Tliis allows, for example, an 
Open Directory Master to integrate data from Active Directory 
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witliout having lo be itself bound to Active Directory. This 
allows for a great deal of flexii>iitly, aMiough my personal 
experience with directory mode has been inconsistent, 

This does bring to inind one annoyance witli directory 
service handling in Mac OS X in genentl, iti^d that Ls how 
dependent it is on seardi order. If the search order in Directory 
Access is incoirect, youVe in a world of hart. As well, from wluii 
1 can tell, if yon have two external directory systems defined, 
and you try to autJjentiaUe, and the first one can't authenticate 
you, the directory services code won't fall through to the next 
one, and you can’t authenticate. This is ju.st a little annoying. 

However, wlien directory mode in Workgroup Manager is 
working, and you have your authentication paths set right, ifs 
neat as heck to use. 

New Features 

Since this is an article alx>ut Mac OS X 10.4 Server, I'm 
of>viously going to concentrate on the new features that are in 
Mac OS X 10.4 Server that relate to WorkgR)up Manager. This 
isn’t really a Wijrkgrouf) Manager review- I'm just using that 
prcxlucl as a fratnework. One change lias to do wiiii the new 
“Directory Aclmin'' user concept. This just allows you to set op a 
Server so that the local tnachinc administrator Is not, by default 
Uic directory administrator, and in fact, the loc'al adininistraior 
account thill you first set up is a Netlnfo only account, not an 
I.DAP account. A .second new feature is the Search lnutton in the 
Workgroup Manager toolbar that allows you to search the Open 
Directory database by a number of itenis, such as IJserlD, Real 
Name, Comment, etc. If you have UioUsSands of records in your 
Open Directory domain, that’s a right handy feature to have. 

User Accounts 

The first olwious changes are due to the ACLs in Mac OS X 
10.4. The ok! l6-grQup limits are gone, and there’s support for 
inherited groups. As 1 said in July's article on this, ACLs give you 
great power, l>ut you have to lie careful, especially if yau'w 
talking about combined Active Directory and Open Directory 
networks. Qtreless application of ACLs will create security holes 
the likes of which you’ve never seen. Setting up groitps tor a u.ser 
is still the same, although there's a new option for seeing 
inherited groups. 'Hits is for AQ, usage, since you can have 
explicit and inherited permissions and groups. Mail and Print 
setup liasn’t changed, although with the improvements to Mac 
OS X 10.4 Server's print architecture, die existing features 
probably work much l>ctler. 

A new feature in Mac OS X 10.4 Server's client management 
is the Info tab for user accounts. This aNows you to directly enter 
personal information on a user such as name, address, IM 
handle, etc. Tliis is not a requirement for the account lo work, 
but is a convenience for those using Open Directory as a siiared 
address lKK>k. You could do this in Mac OS X 10.3 Server, hut 


you had to directly edit the directory infomiadon, and it didn't 
always work correctly. 



Workgroup Manager's Info Tab 

The Windows settings for User accfiunis is unchanged, and 
the Inspeaor tab has only minor changes, such as showing the 
.size of each entry in the user’s record. One thing that hasn't 
changed from Mac OS X 10.3, and I really wish would, is ilic 
pane management in Workgroup Manager. You can’t resize the 
panes in WorkgriJtip Manager to show more info. You need to 
see die full Generated UID number? Changing the si/r of the 
window only increases the size of the account ILsling on the left. 
'Ihe data display on die riglit cannot l>e grown or shnink 
depending on your needs, so get to scrolling. Shades of Windows 
3.X! For a company thai gets U! right far more than most, when 
they get it wrong, it’s dtiubly frustrating. 

Adding new users is unchanged, and still as kludgy as ever. 
Apple really needs to step up its sysadmin automation 
capal">ilifies here. With regard to individual user preferences, 
there are a few ufxlates here. The login prefs have some new 
features, such as “^Add network home sliare point" and ’'Meige 
with user’s items (Mac OS X 10.4 and later). The first one is how 
you make sure die user’s network home share point always 
mounts, Tlie second one, from what I can lell, Ls Lo meige die 
user’s personal startup items and the ones you select for them so 
they all .start up on login. I say, “from what I can tell”, lx;ciiusc 
tills chccklxix is pretty much undtKiimented. Apple’s PDF and 
discussioas group don't liave anydiing on it, (at feast not as of 
this writing, which is alxmt a month liefore you read it) and 
searcliing the Apple Knowledge Base for tliai item gave me no 
results. Spotty doc:umenlalion for a user is bad. Sjxitty sysadmin 
drx:umenialion is unaccepUibfe. If they can take the time to cmie 
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the function and the UJ access for it, liien A[>ple niusi take the 
time to document Us basic function. Login Items is the only 
preference tliat you can manage for users or groups in the 
Workgroup Manager login preferences. 

This gives me an opening to bring up a jxnnt alxjut 
Workgroup Manager and ihe MCX (Managed Client OS X) here, 
lliere are three levels of management in MCX: User, Group, 
Machine, Most, but not all prefs can Ixr set at all three levels. If 
you have comradtclory settings, you may not get the results you 
want and you'll have great agony. You want to be very careful 
alxnit setting the same preference on multiple levels, and dt) so 
as littie as iK)s,sil>le. Simple planning tefore you set will help 
here. Along these lines, Apple including a "Settings Check" 
fund ion that would, if nothing else, highlight possil>Ie conflids 
would l>e (juite useful and very welcome. 

The Media Access [)refs haven't changed, bur 1 wanted to 
point them out. If you have a need lt> limit how pcttple Cdtx use 
remtwablc mtrdia, this is an important .setting. It allows you to 
lock down access w removable media at whatever level you 
require, with decent granularity. In UJcJay's SOX/GIB/HIPAA 
environment, !>eing alile to not allow copying of data Co, or even 
from, removable media is an important feature, and fm glad that 
Apple makes setting this ui> a,s easy us they do. 

The Mobility setting is the biggest change to user 
manugemenl in OS X, an<l one that’s beeti a long time in 
coming. With Mac OS X 10.3 Server, you could have "mobile” 
accounts, but all that did was deal %vith domain authentication. 
It did noitiing for data ,synchioniz:iik>n. So, if you had a rm^lnle 
account on one machine, and went to another machine, you 
didn’t have any acces.s to your home directory data on lire first 
mat'hine, Mcibile accounts under Mac OS X K).3 really only 
allowed you to log into the machine in situations where you 
were disconnected from tlie Open Directory network. In Mac 
OS X 10.4 Server, thaPs changed, and you now luive (almost) 
full home diredory synchronbiition. You can ch(K>se the items 
you want, or don't want to sync, and how. St), for example, you 
can have some direciories sync trn krgin arid logout, (this woitld 
l)e tile Windows Uoaming Profile mtxlel), or have them sync in 
the background anywhere from once every S minutes ft) once 
an hour. You prolxthly want to sync as little as jxjssihle to avoid 
neiwtjrk capadiy problems. 71iis meaas rliat if you have to 
switch machines a lot, you can have an almost uniform home 
directory setup, something that will be a inajt)r boon to mt>bile 
users, or schxx)ls, wliere a .student may log into multi])le 
machines thitxighout the day and then uike a laptop home. 
There is one exception: Your home Library dirt'ctory, Hiai ik>es 
not sync, even if you tell Workgroup Manager to swnc it. This is 
primarily Ix'cause you have some applioition and OS settings 
that use absolute hard ctxlecl paths that could break on different 
machines. Switt:hing machines a lot will also make your ByHtxsl 
preference management a iot more complicated. 'Iliere is a 
workaround for this, at 

http://wvvw.af p548.com/article, php?story=2005060110143632 
3, but Ix' warned, fort:iog that .sync on cause problems, so lx: 
careful However, even wiilt that caveat, this is a ferature that 
many have needed for a few years, and finaliy liaving it, even 
in this imfxrfect form, is a welcome change. 



Portable Home Directory Sync setup 


3’he Network preferences are a new' feature, allowing 
administrators to set proxy preferences at the domain level, so 
tftai users can\ bypass them. 'Hie Software IJpcHte prefs, also 
new' in Mac OS X 10.4 Server, allow you to specify a local 
software update server you wish your users to use. 

Group Accounts 

At the group level, most of the account cliangcs arc 
wrapped around ACLs, so you am have groups within groups, 
etc. lltere are some other minor tweaks, like a group pictiire 
feature, and a comment for die group. OuLside of preference 
features tliat tion't exist at all in Mac OS X 10 3 Server, group 
[>refefences are unchanged. 

Computer Accounts 

This section fias received more than a little work in Mac OS 
X 10.4 Server In the Access tab, ytiu have Mac OS X 10.4 - only 
options ft>r Hx^al — Only accounts picking workgroups from die 
list of groups allttwed to access the mat ltines in a computer list, 
and that computer administnitoi's can disable management. 

However, ilie specific machine information ft>r Macs in a 
Computer Lisi has grown by (jUite a bit. In Mac OS X 10.3 Server, 
alxxit all you could do was set the iomputer list for a given 
machine, give it a name for use in Workgroup Manager, and a 
comment. In Mac OS X 10.4 Server, there are some new features 
here that work with tlie managed Network views. (Ill be getting 
to tho.se later). So you can .specify wliat Network view a 
machine can use, an<i the UILLs that t^in be used to reach the 
computer based on wliai services it offers that you want used. 
So you on specify Al’P, SMB. etc. When we go over managctl 
Network view.s, you1l see how jx>werftjl this can lx. 

In the preferences, again, tliere aren't many changes that 
aren't Mac OS X 10.4 specific. Tlie Login preferences arc a little 
different for machines, in that you not only have features that 
only apply to tlie Lxjrnputer level, hut you can now specify 
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login and logout scripts that mn instead of, or in addition to 
Login/LogoutHook scripts. This is a powerful, and potentially 
dangerous feaaire, so it only works if you enable this feature 
for rotjfs login window defaults AND you are using trusted 
binding to an Open Directory domain. 'I'his makes sense, as 
without that precaution, you could create a rogtie server that 
would run 'bad' scripts on Macs that you shouldn't have control 
over. That would 1x3 A Bad Thing. And scripts have to be 30KB 
in size or smaller. 

All Records 

'Ihis (optional) tab hasn’t ckinged in any noticeable way for 
Mac OS X 10.4 Server, and while tliat's gotxl froni a familiarity 
jx>int t)f view, it perpeiiiates one of the worst design decisions 
ever made, and tliat is llie decision to hide the stmeture of the 
directory from the humans. Witli almost any other Dinccfory 
Service, sucli as Active Directory, you can see the tree view of 
the directory, and easily manifmlaie the data directly. So you can 
drag and drop items Ix^rw'cen OUs, groups, containers, etc. 
Workgrt>up Manager still doesn't allow you to do this, which is a 
shame, (because even with Mac OS X 10.4 Server’s rudimeiitary 
OU support, being able to handle tJiose ol>jecis easily would 
make directory setup and admini.stration far eusicT. L get ilia! a lot 
of K-12 adminisiralors don i want or need this kind of feature, but 
almost every other segment dtx3s want and nectl it. In the 
Enteq^rise Space, Workgrf>up Manager is one erf the weakest 
directory management tools on the market, and things like tliis 
are li big part of it. Aj^j^le needs to, at leusi for Ijeopard; 
preferable well before, let the administrators who need thi.s 
ability have acce.ss lo it via Apple's own tools. Otherwise, you'll 
never be able to really scale Open Diredory past a relatively 
smallish size. 

Managed Network Views 

Thi.s is a brand new feature for Mac OS X 10.4 Server, 
accessed, i>y clicking the Nettmrk button in Workgrotip 
Manager, and in the short version, allows you to manage what 
your users see when diey click on the Netmtrk icon in the Mac 
OS X lO.i Finder. One of the problems with the Network view 
in Mac OS X 10,3 tliai resiriaing what any Mac .saw was quite 
hard, even effectively imfx)ssib[e. With Mac OS X 10.4 and Mac 
OS X 10,4 Server, you can now manage what neigliboriicKKls 
and what machines any given client in an Open Directory 
domain c.an see. If you have a small network, this is not a big 
issue for you. if you have a few thousitnd clients on multiple 
subnets, tliis is a real lielp in controlling spurious browsing imd 
its associated tniffic. 

Tltere are three main kinds of views; 

1. Named View: Tliis is a network view ihai is visible only on 
those! c'ompiIters that you explicitly allow access for. 

2. Default View; This is used for managed computers if there's 
no Named View, 

3. Public View: ITiis is used in lieu of llie otlier two. If there's 
no Pufjlic View, but there is a Default View, dial's used 
instead. 


Within a Network View, you can have one or more of the 

following objects: 

• Network Neighborhood: This is a colledion, (with a name 
stolen right from Window,s, yeah, both sides do that), which 
can contain any of the three object types listed here. So it 
can contain individual computers, oilier Neiglilxxhcxids, or 
dynamic lists. It's a catchall that you can use as a rtxit 
container tyix*. 

• Computer; 1'his is well, a computer. Specifically, it's a 
computer that Wtirkgrnup Manager knows about. You 
can add computers directly to a View, or to a 
Neighborhood. ITiis allows you to better partition your 
browsing traffic, .so you could, for example, have a 
Named View called “Directory Servers" and have only 
your Open Directory primaries and replicas listed there, 
and another Named View called "File Servers" which 
could contain Nelghborlioods like ‘'SMR Servers”, "AFP 
Servers”, etc. 

• Dynamic List: Tliis is a collection of resources that is 
created on the fly when you access it in the Finder Unlike 
the txher two, you cm only create a dynamic list from 
existing network simciures, as seen below: 



Dynamic Lists are useful when you want to limit browsing 
and already liave service di.scovery strucnires in place. Note 
that you can neither manually add nor remove items from a 
Dynamic List. You can however, put a Dynamic List in a 
Neighlxirhood and manage acce.ss in that fashion. 

Once you have created your view types And the objects 
they contain, you can now manage tlieir visibility, l>y either 
having the various views add to the unmanaged Finder 
Network Views, or rcfilacing the standard Finder Network 
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view entirely. *rhis is a powerful uxH rf you need to limit 
access to various computers on your network, such as not 
allowing random access to the accounting servers, etc. It is 
also a good way lo ensure that every computer isn’t tiying to 
browse entire network structures that they may have no need 
For. limiting this kind of traffic helps enhance overall 
network performance, not just for the administrators, but for 
the users as well. If a user only needs access to four file 
servers^ making them wait wliile an unman aged browser view 
enumerates 150 machines is a waste of their time, not to 
mention bandwidth. 

Sharing 

ACU are, again, the main .source of changes here. In the 
Aii tab, you have the o|>lion to enable ACLs on a given 
volume. Note that tins can only be done at the volume level, 
and outside of Workgroup Manager, you can only do this via 
fsaclctl. Once that's done, you can then apply ACLs to 
specific folders and files within that volume at your 
di.scretion. This can be done outside of any sharing you may 
implement for a folder, and unlike sharing you can set ACLs 
on files too. Remcrnl^er that Tve been saying he careftd wilt 
ACLs a lot? Tliis is why: 



ACLs give you a tot of capabilities, hut .setting them willy- 
nilly, and not watching how you set groups within groups, or 
tracking who is in what group for which ACL entry will, not can, 
but Will cause you problems. One benefit of Apple's 
implementation is that if you do get into troulilc you can, as a 
last resort, turn ACLs off and start over again, I know Windtiws 
Admins who would love to do that, because they accidendy 
created an ACL for a folder that not only keeps everyone out, 
but won't even let them delete it widiout reformatting the drive 


or oilier very drastic action. 

I don't want to scare you away from ACLs, but you need to 
give them a lot of respect. As tlic disclaimer says, not intended 
far amateurs. 

Outside of ACLs, sharing hasn't changed much. There's 
some improvement to the strict locking for SMB shares, 
(Note: You sliould only enable oplocks on shares that will 
only be touched by Windows clienLs.), Iml from the 
Workgroup Manager point of view, sliaring’s pretty much the 
same as it was in Mac OS X 10.3 Server, you ju.st have juicy 
ACL goodness. 

Conclusion 

That’s it for part two of this series. It's quite a bit shorter 
than the Server Admin part was, but then Server Admin is the 
ba.sis for most of w'hat Workgroup Manager dcx?s, so lliere’s not 
as much change to talk about. The final part of this series will 
show up next month, and cover, well, everything else. 
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Opening a file from clafJSic Mac OS (pre Mac OS X) with 
fsWrPerm, IsRdWrPerm, or the clefaiiit fsCurPerm, [iieani that 
any orher application trying to open that same file with 
write access would not be able to do so. Usually, an 
fsRdWrPerm error would be rerurned when other attempts 
were made to 0|Km the file for write access, though 
aUempis lo open such a file for read-only access would 
succeed. This default behavior allows for one “write” and 
multiple "readers" of the file. 

Mac OS X's BSD subsystem does ntjt enforce file 
read/write privileges in the same way as classic Mac OS. 
Opening a file for writing docs not ensure other processes 
can not write lo the same file. Tlve default beliavior of BSD 
allows for multiple "^writers" to a single file. As a result, 
opening a file via PBHOpenDF, PBHOpenRF, PBHOpen. 
PBOpenFork. FSOpenFofk, HOpen, etc., on a local volume 
and passing in a permissions value of fsCurPerm, fsWrPerm. 
or fsRdWrPerm does not guarantee exclusive file access on 
Mac OS X. On Mac OS X, subsequent Open calls to open a 
file with write permission may succeed without error 
Similarly, the PBLockRange() routines may not actually 
guarantee byte ranges that cannot be modified by other 
processes. Because these routines may return wiiiumt error, 
you .should check out the availability of exclusive file access 


(see “Checking Availal>ility of ExcUtsive file Access”) before 
making any assumptions about the underlying file access. If 
the "supports advisory locks” feature is not available, your 
application will not know if the File is already in use by 
another application. 

A[>plcSliare servers and Personal File Sharing on Mac OS X 
do enforce exclusive file access and range locking For volumes 
accessed over the network. However, tliis functionality is only 
available when accessing files over a networked file sharing 
connection and is not available to applications running on the 
server itself. 

Guidelines for Working with Non-exclusivity 

You should realise that many applications relied on the 
iK'havitir of the classic Mac OS File Manager to preveni 
multiple applications from writing to the same file (or to 
control write access through byte range locking). Since that 
behavior is not implemented in all versions of Mac OS X, 
some common workarounds that you may wish to use in 
your code are described below. BSD was designed without 
exclusive locks in order to prevent denial of service attacks 
in which one process opens a tile with an exclusive lock 
which may be required l>y another process, effectively 
blocking the other process. 
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Checking Availability of Exclusive 
File Access 


Mac OS X will enforce exclusive file acceas, ie, one writer 
and many readeni of a file, through it^ application frameworks, 
Cartion, Cocoa, and Java by enforcing BSD advisory locks as 
though they are exclusive. Tlie “supfx>rts advisory" l(K:ks^ 
feature is deftnetl if IxXh the OS and file system for the volume 
in question support advisory locks. In this case, the default 
behavior of the application frameworks is to open files with 
exclusive access w hen opened as writalile. Applicatkms built on 
these frameworks automatically get this functionality and do not 
need to be modified. When the conditions are met to support 
exclusive file access, PBLockRange will also call down i[in)ugh 
to the l^SD advisor)" locks. Sincr PBLc>ckRange will l>e based on 
BSD advisory' locks at this point, range locks can be applied to 
loc'al files as well as tluxse t)n file servers. 

Since not all versions of Carton on Mat' 05 X support 
exclusive file access nor do all file systems suppoit BSD advisory 
locks, you should check a couple of things tofore making 
assumptions atout the underlying file access Ix'liavior You 
sliould only assume the.se features are availal>le if the gestalt bit, 
gestaltFSSupporlsExdusfveLocks, as well as the GetVolParms bit, 
bSupportsExdusiveLocks, are Ixjth set For instance, the CarlTon 
Framework File Manager rotilint,‘s supjx>rt advisory loc'ks by 
default when SupportsExdusiveFileAccess returns tnie, 

//ifndef gestaltFSSupporlsr.xc l ufiiveLocks 

//define gestaltFSSupportsExcluslveLocks 15 
^define bSupportsExc KielvnLocks 18 

tfondlf 

Boolean SupportsExcluslveFileAccesst lihort vRefNuin > 

I 

OSEcr err: 

GetVoirermslnfoBu f for volParmsBuffer: 

HParaniBlockRec hPB: 

long response: 

Boolean excluRiveAccess “ 

false: 

err Goscaltf gestaltSystemVersion, ^fresponRe ): 
if ( {eri = noEtr) (response < 0x01000) ) 

I 

err = Gestalt( geRtaltMacOSCoapatibiiityBoxAtir, 
^response ); 

if { (err noEtr) 

II {(response & {1 << 

gestaltWacOSCompatibilityBoxFresent)) = 0) ) 

retiittiC true ): // Running on Mac 

0$ 9 , not In Classic 
J 


err - GestaltC gesialcFSAttr, ^response ): 
if ( (err noErr) 

hh. (response & ilL << 
gesLaitFSSupportsExcluslveLocks)) ) 

( 


hFB. loParaia.loVRefNum 
tiEB. loParari). ioNamePtr 
hPIi.ioFaram. toBnffer 
^volPactnsBuffer; 

HPB, ioFarani. ioReqCovint 


= vRefNuHi: 

^ NULL: 

“ (Ptr) 

= siaeofC volParmsBuffer 


err “ PBHGetVolFarmsSyncC &hPB ): 

If C err = noErr ) 
exclusiveAccess “ 

(volParmsBufter,vHExtendedAt tributes 
& (IL « bSupportsExcIiislveLocks)) 1“ 


0 : 

\ 

reLurn( exclusiveAccess ): 
J 


I'o check if a volume supports byte range locking via 
PBLockRange you shoiild check the bHasO pen Deny bit rciuEiied 
from GetVolParms. See Technical Note FL37 
(http://developer.applexom/technotes/fl/fL37.html) for more 
informaiit>n alK^ui PBLockRange details. 

Common Workarounds 

The following tw^o lechnicjiitis are fretjuently used to work 
around this issue on pbtfonus tliat do not enforce exclusive file 
access. 


Lockfiles 

A common approach usetl by many developers is lo create 
a "lockfile"' in the same directory as the file being opened. 
Whenever opening a file, "fot>\ for instance, with write atxress 
you first try to cTcaie a lockfile, *Too.kx:k‘', in the same IcKatioii. 
If the file creation fails tocaiise the file already exists, you 
assume “fto" is already open by another application. Upon 
ckxsing “fcK)** the application is also responsible for deleting 
"‘fcKjJtK'k''* A strength of this technk|ue is it only makes one 
assumption alx)iit the underlying file system; the file creation 
operation is atomic. The obvious weakness Is that since there Is 
no 05 siipjjoit for this metliod, each application is responsible 
for implementing its irwn Unik file mechanism, and there artt no 
agreed upon siandards or conventions for the naming of lock 
files. 

Edit a Copy 

Ariotlier workaixiund relies on operating on a Linique copy 
of the file. When a file is opened for editing, a duiilicate of the 
file is created in /imp directory with a unicitie name, and 
optmed. When the user tries to save the document, the 
inodification date of the tiriginal Is matched against the date 
cached during the open of tlie file. If it has changed, you know 
the file was modified. 

MAC OS X Solutions 

BSD Advisory Lockiiis 

Although Mac OS X's BSD subsystem dtx?s not implement 
provisions for exclusive write ac:cess, (i*e. mandatory locks), it 
does provide advisory IcK^ks. An advisory lock is a voluntary 
Ifxking mechanism in which the underlying file system 
maintains a linked list of reerxd locks. As long as your 
application and other applic:ations respect the locks, only one 
application at a lime will have write access to a particuiar file. 
Since tliese locks are voluntary it is the choicc/responsibility of 
the application developer to respect or ignore advisory kK:ks. If 
you would like to use advisory locks, this c:an to" done by 
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following tlie instmctions later in this aitide. By accessing files 
tlirough tlie application frameworks (Carbon, Cocoa, Java), in 
versions of the OS supporting tlie advisory l(K:ks feature in 
frameworks, this will be provided automatically if you use the 
framework’s file access methods. 

Applications that call BSD file I/O functions directly will 
not gain this behavior for free, and therefore should l^e revised 
CO set and respea advisory lcx!ks by specifying the appropriate 
flags when opening a file. 

You should evaluate changing calls from: 

fd - open( “./foo**. 0_RDWR ); 
to 

fd - open( 0_RDWR + 0_EXLCGK + OJIONBLOCK ): 

Where, 0_EXL0CK means Atomically obtain an exclusive 
lock, and 0_N0NBL0CK means Do not block on open or for 
data to become available or Do not wait for the device or file 
to be ready or available. 

Implemeating Advisory Locking 

Anywhere you are calling the System, fra me work version of 
open<2) with write access, you should modify ihc parameters to 
include tlie ^O.EXLOCK + O^NONBLOCK' flags, and kindle 
errors being returned, where tfiey may have succeeded in tlie 
past. The open(2) call will thcji fail if die file lias atready Ix^en 
opened lor exclusive access liy another process. 

Advisory locks are associated with a priKCss and a file. This 
lias two implications: 

• When a process terminates all its locks are released. 

• Whenever a descriptor is closed, any locks on the file 
referenced by that descriptor are released, 

laipleiiienting Byte Range Locking 

liSD also provides advisory byte range locking support 
througli the fcntl() funttion. By using advisory locking, your 
applic-ations will be able to work in a ccKiperative with Otrbon, 
Classic, and other applications in the future. In these 
circumsttinces, files should lx.- opened with the 0_EXLOCK set and 
then ranges ItK’ked through die fcntl{) call 

Stevens' ‘'Advanced Programming in the UNIX 
Environment’' (j>age .^67) dest rilies some techniques for using 
the UNIX service fnctl() to Icxk portion of a file for reading and 
writing (Stevens, 1999, p, 367). 

Warning: A file kx:k rex^uest which is lilcKked can lie 
interrupted by a signal In this c'ase the lock operation returns 
EINTR. TliiLs you may tliink you got a lock when you really did 
not, A solution is to blcxh signals wiien icxrking. Another solution 
is to test the value letumcd by the l(x:k operation and relock if tlie 
value is EINTR, Another solution, wliich we atkipt here, is to do 
nothing alxiui il 

Recordmg Locking Is die term normally used to describe die 
ability of a process to prevent other pnx'esscs from modifying a 
region of a file while die process is reading or mexlifying that 


portion of the file, BSD provides access to iis remrd locking 
mechanism tlirough the fcnll function: 

ihnclnde <sys/types,h> 

^include <unistd.h> 

^include <fcntl.h> 

/- 

* Returns: 

* -1 on error 
“/ 

int fcntl(int flledes, iat emd, , /* struct flock 
-flockptr */ ); 

We’ll Start with the third argument (fitKikplr), which points 
to a fltxk strut:ture: 

struct flock I 

short l_type; 

/• F„RDLCK (shared read lock), or 

* F_WRLCK (shared write lock). or 

* F_UNLCK (unlocking a region) 


off^t l_start; 

/* offset in bytes, relative to l^whence */ 
short i_whence: 

/“ EEEK_SET: file’s offset is set to 

* l_start bytes from beginning of file 

■ SEEK_CtJR: file’s offset is set to its current 

* value plus the l_start (which can 

* be + or -) 

* SEEK__END: file’s offset is set to the else of 

* the file plus the 1 .start (which can 

* be + or -) 

*/ 

off.t l_len: 

/* length of region! in bytes 

* special case: if (l_Ien ’=*0), it means that 

* the lock extends to the largest possible 

* offset of the file. This allows us to locX a 

* region starting anywhere In the file, up 

* through and Including any data that is 

* appended to the file 
*/ 

pid_t kpld: 

/* returned when cmd F_GETLK */ 


This Structure descrilx's: 

• 'Ihe type of Itxrk desired (i.e. read lock, write lock, unlock) 

• The starting byte offset of the region txing lixked or 
unkxked (Lstan and Lwhence) 

• rhe size of tiie region (l_len) 

To Icx'k an entire file, set Lstart and Lwhence to pi>inl to 
the beginning of the file (i,e, Lstart= 0, l_whence= SEEK_SET), 
and specify a length (Lien) of 0. 

Any number of processes can have a sliarcxl read lfx:k on a 
given byte, i>ul only one pnxess can have an exclusive write 
[(Kk on a given byte. To obtain a read kx'k the descriptor must 
he open for reading, anti the region cannot have an exclusive 
write lock. To obtain a write lock the descriptor must lie open 
for writing, and the region cannot have an exclusive write lock 
nor any read locks. 
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Now, we will describe the second parameter (cmd.) for 
fcntl. The possible commands and what they mean are 
descril:)ed in the following: 

• F^GETLK: Determine if the kyck described by flockptr is 
blocked by sonic otlier lock. If a lock exists tiiai would 
prevent ours from !>eing created, ilic infoniiation on that 
existing lock overwrites the information pointed to by 
flockptr. Lf no kx'k exists ilKit would prevent ours from Ix^ing 
created, the statciure ixDmted to by flockptr is left unchanged 
except for the Ltype member, which Ls set to F_UNLCK, 


Int ]pck_reg{lnt fd, int cmd, 
inc whence. off_t len) 

I 

struct flock lock; 

lock*l_type type; 

F_UN 1 ,CK * / 

lock.i^etact = offset; 
to l_whence */ 

lock,l_whence - whence; 
SEEK^KMD */ 

lock,l_leh ^ Len; 

EOF) */ 

return ( fcatKfd. cmd* 

) 


int type, eff_t offset, 

/' F_RDLCK* F_WRLCK, 

/* byte offset, relative 
/* *SRRK_SE7, SEEK_CUR* 
kbytes (0 tneana to 

ilock) ): 


• F_SETLK: Set the kxk described by flockptr. Tf we are unable 
to obtain a lock (because of previous Itxks already granted 
for the region) then fenti reiuras -t and ermo is set to either 
EACCES or EAGAIN. 

* F_SETLKW: This command is a l)kx:king version of F_SETLK 
(the W in the cx>mmand means *^vair). If the retjiieslcd read 
kK:k or write lock cannot he granted Ixcause another 
process currently has some part of the requested region 
locked, the calling prcxress is put to sleep. This sleep is 
internipted if a signal is caught. 

Be aware that testing for a lock with F_GETLK and then 
trying to obtain that lock with F^SETLK or F_SETLKW is not an 
alornic ofieration. We have no guamntec tliat lietween the two 
fcntrl calls some other pr<x:es,s won't come in and obtain the 
same lock. 

Tcj save ourselves the trouble of allocating a flock stmcaire 
and filling in all the elements each time, Stevens defines the 
function lcxk_reg and a number of macros dial call it. Notice 
that the macros shorten tlie numl^er of parameters l>y two, and 
save us from having to rememlxr the F_* constants mentioned 
above. 

#define read_lock(fd, offset, whence, leu) \ 

loclc-reg tfd* f_SETLK, P_RDLCK, offset, 

whence, len) 

i)deflne readw_tock(fd. offset, whence, ien) \ 

lock.reg (fd, F_SETLKW. F^RDLCK, offset, 

whence, len) 

jjdefine write_lock(fd * offset, whence* lenj \ 

iock_reg (fd, F SETLK, F_WRLCK. offset* 

whence, ien) 

^define writew_lock(fd, offset, whence, len) \ 

lock^^reg (fd, F^SKTLXW, F_WRLCK, offset, 
whence, len) 

^define uB_lock(fd. offset, whence, Ien) \ 

lock.reg (fd. F.SETLK* F_UNLCK, offset, 

whence, ien) 


pld_t locic_test (int * Int , off_t , int , off_t ): 

^/define is_readloGkCfd. gffaet* whence, len) \ 

lock.test(fd, F_RDLCK. offset, whence, ien) 
//define ls_wrltelock (fd, offset* whence, len) \ 

lock_test (fd, F_WItLCK, offset* whence, len) 


pid_t lock_teflttint fd* int type, off_t offset, int 
whence, off_l len) 

I 

struct flock lock: 

lock.l_type « type: F.RDLCK ot F_WRLCK */ 

3ock,l_start = offset; /* byte offset relative to 
l_wherice */ 

lock,l_whence = whence: /* SEEK_SET, SEEK.CUR, 

SEER^ENb */ 

iock*l_len = len; /‘ /kbytes (0 neans to EOF) */ 

if (fcntl(fd,F_GETT,K,Mock) < 0) f 
perror(**fcntl“): exit(l) ;J 
If (lock*Ltype =« F^tMLCK) 

return (0); /* false, region is not locked 

by another process */ 

return (lock.l_pid): /* true* return pid of lock owner 

J 

There are three important niles regarding automatic 
inheritance anti release of rec:ord kKks: 

• kK'ks are as*s(Kiated with a prexess and a file. When a 
prtxess teniiinates, all its Itxks are released. Whenever a 
descriptor is closed* any lixrks on the file referenced by that 
descriptor for ifiat process are released. 

• Locks are never inherited by the child acrtxss a fork 
(otherwise we could end up with two prxxesses sliaring a 
write lfK:k) 

• Locks may he inherited by a new program aot>ss an exec. 
This Is not required by BSD and is tlierefore machine 
dependent 
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Q UICKTIME TOO^KIt ^ byTimMpnro0^ 


_ Threads _ 

Performing QTKrr Operations On Threads 


I n the previous three articles (in MacTech, May, June, and July 
2005), we have investigated the QTKit, Apple’s new framework 
for accessing QuickTime capabilities in Cocoa applications and 
tools. We have used this framework — introduced in Tiger and also 
available in Pantlier with QuickTime 7 — primarily to build a 
sample application that can open and display one or more 
QuickTime movie files (or other media files openable as 
QuickTime movies) and diat supports the standard suite of movie 
editing and document management operations. 


Introduction 

Tlie sample application that wc 
have been developing, KilBc^z, perfoims 
really <|uile well. Files oixni and display 
quickly, and cut-and-paste editing works 
as smootlily as could l>e expected. And, 
as mentioned in one of tlicxse previous 
articles, QTKit-based drag-and-drop 
perforiruince in most instances greatly 
cxcc'cds that provided by the suindard 
movie contn>ller c:omponent 

But, truth lx told, we haven't really 
asked Kilfez to handle any fxHenLiatly 
slow^ operations. Currently it can open 
only flies selectable in ihe lile-opening 
dialog lx>x, which meiins that we're not 
likely to see any real delay wlien oixning 
a niovie file. If KitFe/ were to support 
files specified by remote URLs, we'd 
definitely see some slowdown in movie 
opening. Also, some operaiions tlKit we 
c^n perfonn using QuickTime funaions 
— like importing or exporting movies 
and large piciure.s — can take a 
considerable amount of Lime. If Kithez 


wett* to support those sorts of operaiirxTS, wekl want to make 
sure tlial ihe user was able to keep working while tliey are 
churning away. Tliia genenilly means that we'd need to learn 
how to pertbmn QTKit oixmtions on a I’xickgmund tliread. 

In this article, we Ye going to lake a look at i breading 
and Q7'Kit. vSince QTKit Is built on top of QuickTime, ii 
inhcTiLs whatever limitations exist in QuickTiitie with 
regard to Ixing able to perform cjfxrations on backgnxind 
threads. QuickTime has supported threaded t^fxrations 
sinc’e Mac OS X 103 and later, wiili QuickTime 6,4 and 
later Tliai is to siiy, it's now possiltle to move potentially 
time-consuiiiing operaiions to a background thread, 
thereby freeing up the main thread for user interaction. 
Gone are the days when importing or exporting a large 
file invariably ties up your QuickTime application. 

To achieve this, wet I need to use a few new 
QuickTime fimetions to set up the QuickTime environment 
on a liackgrtjund thread. We'll need to learn how to safely 
move Q'lKit objects I xlween threads, and wx’ll need to lx 
cTireful alxiut whicli o|7eralir)ns are performed on a 
backgrt)und thread. But with these three issues cewered, 
we should be at:>le to prr>vide a far better user experience 
than is possible in a single-threaded appUcaiion. 

Before we begin, a couple of provisos. Ti would be 
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gocxi if* you were ^ilrciidy familiar with application 
ilireading in general and with Cocoa's NSThread class in 
particular. If not, don’t worry; you should be able to pick 
up what you need along die way. Just don't expect a 
detailed discussUin uf tlireading mtxlels here. Also, I will 
lx‘ focusing vn invoking QlXit and other Ctxoa methrxls 
on background threads; see the dtxunients mentioned in 
the References section for more complete infonnation 
about threading in Quick'rime generally. 


selector Lor f 1 oadStateChanged:) 

name: QTMo vieLoad S t a t el) i d Cha n geNo 11 f i c a t ion 
objectitfioviej: 

] 

Whenever the ioiui state of the downloading movie 
changes, Uie loadStateChanged: melhtxl will be called. 
(See “Loadecr in Mactech, Sepicnilx^r 2002 for a complete 
discussion of movie load states.) One easy (mplemeniation 
of loadStaleChanged: is .shown in t.isiing i. 


opening Movies Revisited 

As mentioned abrwe, our sample application KltKez 
currently can open only files selectable in the file-opening 
dialog fxix, whicli generally means that it will Ix^ opening 
only Itxal files. In the previous article, we saw that we am 
also use the initWilhURL:error: methocl to open a ncmiotc lile 
spet’ificd by a URL. To elicit a LIRf. from the user, we might 
display a dialog box like the one in Figure 1. (Adding this 
dialog lx:>x to KilFez is left as an exercise for the reader.) 


Listing 1; Handling load state-changed 
not! fleat ions 

- (void) loads La leChanged: (NSNot if ication * Inotificat f on 

I 

if [ I [movie attrl 1 juteF{>rKey:QTHovieLoadStateAttribute! 

longValueJ >“ kWovleLoadStatePlayableJ t 
ffKSNotificationCenter defaultCenterl 
removeObaervertSGlF 

name: QTMovieLoadSUteDldChangeNotlf ication 
objectiiaoviel: 

[movieView selHovieimoviel; 

[movie release]; 



Figure 1: A URL dialog box 

As you know, initWithURL:error: operates 
asynchronously, just like all the QTKit mcjvie-opening 
methods; that is to say, it returns almost immediately, so 
that our application can continue processing while the 
movie data loads. So we might lx; tempted to immediately 
assign the QTMovie object to die movie view in our 
document window, like this: 

if {[QTMovie canTn1tWith0RL:url]) I 

movie ^ {[QTMovie alloc] inltUlthURL:ucl erTor:tiil] t 
if (iDovie) 

[movieView aetMovie: movie]: 

I 

'I'his would work fine, from the standpoint <jf liaving 
QuickTime download the movie data without Further 
intervention from our application. Experience has 
shown, however, tliat it's best to defer the setMovie: call 
until a sufficient amount of movie data has been 
downloaded, lb do that, we can install a notification 
handler for the OTMovieLoadStateDidChangeNotification 
notification, like this: 

if [ [QTHovie canInltWithURL:iiriJ) f 

movie [[QTMovie allec] InltVlthliRLMUrl erronnil]; 
if (novlej 

[[NSNotificatlonCenter defaultCenterl addObserverisetf 


[{movieView movie] play ]i 

\ 

I 


As you can see, we wait until the load state of the 
movie reaches the kMovieLoadStatePlayaible level, at which 
time we remove the notification listener for the specified 
norificaiion, c'all setMovie:, release our QTMovie object 
(since tile movie view will retain it), and tlien start the 
movie playing. The kMovieLoadStatePlayable constant is 
defined in the QuickTime header file Movies.h. Here is the 
complete set of load state constanLs: 


emm [ 

kMovj eLoadStateError 
kMo vie Li>a d R t a teLoa ding 
kMo vieLoiid S tateLoarted 
kMcvieLuadStatePl jiyable 
kHovieLoadStatePlayIhreu^hOK 
kHoVieLoad S t a t eComp1e L e 
U 


- IL, 

- 1000 , 

» 2000 , 

“ 10000 . 

= 20000 . 

- lOOOOOL 


We need to defer the call to setMovre: until die movie 
is playable to work around a bug in the first release of 
QTKit. If we didn't do diis, and instead jast called 
setMovie: immediately after the call to initWilhURL:error:, 
we would find that the movie view would not 
automatically rediriw itself once any video data had 
arrived. The workaround is simple enough and indeed 
provides an easy way for us to start the movie playing at 
an appropriate time. 

It's also u.seful to know how to get the load state of a 
QTMovie object when we want to add importing and 
exporting support to our applications, ITie reason is 
simple: whenever we want to export or flatien or save a 
movie, we need to have all of its movie and media data 
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on hand. The QTMovie mcLhtKl ihaf we use to export or 
fliiiten a movie, writeTo File: with Attributes:, internany checks 
the movie's load state and returns NO if it's not at least 
kMovieLoadStateComplete. Hut we might need to make 
this check ourselves, when adjusting some menu items. If 
not all the movie and media data is availal^le, then for 
instance the Export... menu item should not be enabled. 
Listing 2 shows a segment of a doc:ument class' override 
of die validateMenultem: method. 

Listing 2; Enabling menu items 

{BOOL)validateHeEUltem: (NSMenuItem *) inenultero 

[ 

BOOL valid = NO: 

SEL action: 

actian = [menultea octioijJ; 

If (action = eaelectortdoExport:)) 
valid ” ([ ImovieView moviej 

attributeForK^yrQTHovieLoadStateAttributel lonj^Value] 

>" kMovlaLaadStaLeCompleta): 

a odicr hues omiued.,. 

return valid; 

I 

Keep in mind that we liave not yet reached a position 
where we need to move any proces.sing oui of die main 
thread and into a secxintLary or background thread. The 
periodic movie tasking dial is retjuired to keep a remote 
movie steadily downloading happens aulomaricaUy on 
the main thread and does not generally consutne so much 
processor time that the responsiveness of the main tlircad 
is adversely impacted. So, although opening a movie 
stxrcified by a URL may take a significani amouni of time, 
QuickTime (and hence QTKit) already knows liow' to do 
that asynchronously without blocking the main thread. 

Importing and Exporting 

Wlien we iiiove into the realm of movie importing 
and exporting — that is, converting potentially large 
amounts of data ~ we cross an important rlireshold. 
Althougli it is c:eitainly possible to export a movie by 
calling wnteToFile:wJlhAttributes: on the main thread, it isn't 
ready advisable, since the call would execute 
synchronously, fisting 3 shows how not to define the 
doExport: metiiod referenced in Listing 2. 

Listing 3: Exporting a movie as 3GPP 

' (IBActlonJdoExpott:(id)sender 
( 

NSlUct ionary ‘diet » [NSDictionary 
dictionaryWithObJectEAridKeya: 

[NSNumber QUjnberWl thBool;YES] . QTMovieExport, 

[NSNumber nujnbcrWUliLojig;k(lTFileType3GPPt, 
QTMovieExportType, nil] : 

[ [iiiovleVlev i»ovio] vriteToFile:@''/tmp/fianipte.3gp" 
vi thA 11 rlbu-tes: diet] : 

1 


If the movie is very large, this metht>d could take quite a 
while to complete. During that time, the user would be 
unable to do anything with our application except move 
window.s around. Not very exciting. 

A slightly better solution involves using the 
movie :shouldContinueOperaiion:wrthPhase:atPercent:withAttri 
bates: delegate method descrilied briefly in the previous 
article. As I mentioned, this is a wrapper around 
QuickTime's movie progress hinction, which we have 
used in earlier articles to display a dialog box showing the 
progress of the export and to allow the user to cancel the 
operation. Figure 2 shows the sheet well display from 
within that delegate method. 



We could implement this delegate method as shown in 
Listing 4. 

Listing 4: Displaying a cancelable progress 
sheet 

- (BOQL)inovie; (QTHuvie *)inovie 

jEbauldContinueOpejration: (NSString •) op 
wlthPhase; (QTHovieOperatlonPhase) plioao 
atPercent:(NSNumber *)p€rcent 
withAttributeo;(NSnictlunary *lattributee 
t 

OSErr err = ooErr; 

NSEvent *event; 

double peroetitDone = [percent doubleValne] * 100.0: 
switch (phase) t 

case QTHovieOperfltionBeglnPhase: 

// set Up the prepress panel 
[progresoText set StringValue:opl: 

[progressBar ffOlDt>ubleValue:0j ; 

// show i(ic progress sheet 

tKSApp beginSheet:progtossPanel 

oiodalForWindow: [movieVlew wrindow] niudalDelegate;Qll 
didEndSelector:ail contextlnfoinil]: 
b teak : 

case QTHoVieOperationUpda tePereentPhase: 

// update the percent done 

fprogresuBar seiDoubleValue:percentDonel: 

[progressBsr display]; 
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break: 

cape QTMovieOperationEndPhaae: 

[NSApp endSheet:pro£ressPaneiJ; 

[progressPanel close ]; 
break: 

) 

// oincel (if fifquKsted) 
event - [progressPanel 

next EventMat chin gHas k:KSLe ft Mo u s e U pMa s k 
untilDate:[KSDate distantPast] 
inModeiNSDefatiltRunloopMcide dequeue:YES] : 
if (event fih NSPolntTnRect [ [event locationinyindow] , 

[cancelButton frame])) ( 
[cancelButton performClick:eelf1; 
err = userCanceledErr: 

) 

return (err = noErr): 

] 

This is certainly a better solution than having no sheet 
at all, but it’s really not satisfactory. Just distracting the 
user with a progress bar is not going to make the export 
go any faster or be any less synchronous. And the manner 
in which we check for clicks t>n rhe Cancel button is not 
really very good, even if it ^ the best we am liope for in 
a non-threaded aj^iplication. 

Threaded Exporting 

So we really do need to move to a mullilhtxradccl 
application il’ wc want to lx- able to provide acceptable 
resjx^jnsiveness in our application's user Interface wiiile 
ixrtbmiing pcxentially lengtliy openitions like exporting a 
movie. As we ll see, spawning a thread to execute some code 
in a Ctxtxi applic:ition is as easy as atlling the IMSThread 
medicxl detachNewThreadSelector:toTarget:withObject:. The 
c:oiTipiexitics wc sfiall encounLcr arise from tlie fact that 
QuickTime was not taigiiuilly written to lx tliread-sale, and 
mxiking it work in a direadetl environment rtxiuires .some 
assistance from the application developxr. For some of the 
tlieory, coicsult tlie dcK'unients listed at tlie end of tliis article, 
particularly the Tech Note on threading Quic^kTime 
applications. For tlie moment, we will content ourselves witli 
tltc pitictica! itiiplications of tliat tlieory. In summary, they are 
these: 

(1) Before any QuickTime APIs (including QTKit methods) 
can be called on a background thread, the function 
EnterMoviesOnThread must lx called on that thread. 

(2) After ail QuickTime APIs (including QTKit merhocLs) 
have Ixen called on a background thread, the function 
ExitMoviesOnThread must be called on tliat tlircad. 

(3) A movie created on one thread that is to be accessed 
on some other thread must first be detached from the 
first thread (by calling 

DetachMovieFromCurrentThread) and attached to 
that other thread (by calling 
Attach MovieToCurrenlThread). 

{^) QuickTime APIs (including QTKit methods) executing 
on a background thread may inrermilly attempt to 


instantiate components that are not thread-safe; when 
that happens, the result cxxle 
componentNotThreadSafeErr (-2098) will l>e 
tetiirned. In that case, you might want to retry the 
opemtion on the main thread. 

Implication (4) has an tmponant corollary. Recall 
from the first article on QTKit that a QTMovie object is a 
CcK:oa reprcscnlation of a QuickTime movie and a 
QuickTime movie controllen That is to say, a QTMovie 
object is associated with a Movie instance and a 
MovieController instance. Currently, no movie controller 
conifxjnents are thread-safe. This means: 

(5)All QTMovie ol)jects must be created on the main 
thread. 

In thec;)iy, creating a QTMovie object on the main 
thread and thett migrating it to a background thread is no 
less dangerous than creating it on a background thread. 
Hxperienc:e has slujwn, however, that it appears to be 
safe to call QTMovie methods on a QTMovie object that 
has been thus migrated. At any rate, this i,s the best we 
c:an do given the current slate of the QTKit and the 
underlying movie contrt)ller components. 

Transferring Movies Between Threads 

To sec how tliese iniplicaUons play out in pntctice, 
let's walk through some code that exports a (QuickTime 
movie on a background thread. If the application's 
Export... menu item is connected to the doExpori: 
tiiethod, we can .start the export process by calling 
detach NewTh read Selector rtoTarg el :withObject:, passing the 
selccLtjr of the ap[^licalion's doExportOnThread: method. 
The doExport; methcxl is shown in Listing 3. 

Listing 5: Starting a background export 

- (IBActioti) doExport: Ci<J) sender 
\ 

NSSavcPp'inel •fJavp.PaTiel * fNSSnv^Fnnel eavePanel]; 

Movie qtMovie ■= [[mov^eVlew movie] qulckTimeMovieli 

Int result r 

OSErr err = noErr; 

result ^ [savePanel runModaiJ: 
if (result = KSOKButton) I 

SEL sel “ @selector(doExportOnThread:): 

[[movleVIcw movie] stop]; 

err = DetacliMovleFroinCurrentTliread (qtMovie) : 
if (err) 
return; 

// show tiic progress sheet 

fNSApp beginSheet:progressPanel 

modalForUindow:[mDvieVlew window] modalDelegate;nil 
didKodSelectortnll contextTnfo■nil]: 

[MJjTliread detachNcwThreadSelector: sel toTatget: self 
withObject:(savePanel filename]]; 

I 

I 
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'I'here is nothing paiticubrly noteworthy here except 
for the call to DetachMovieFromCurrentThread. The 
doExpoil: incihod is called on the main thread, so we 
need to explicitly detach die Movie associated with the 
QTMovie object from the main thread so that it can later 
he attached to a background diread. Notice also dial we 
have moved tiie call to display die progress sheet out of 
the delegate method and into the doExport: methtxl. 

Accessing Movies on Background Threads 

Now let's start building the doExportOnThread: 
method. Its declaration should look like this: 

(T BAc L ion ) doExpor tOriThread: (id) sender; 

Here, the sender object is in fact the name of the file into 
which the exported movie is to be written (as you c:an see 
from Listing 5). uSince doExportOnThread: is to l^e run on a 
background thread, it needs to create and release an 
auLorelease pool, and it needs to call 
EnterMoviesOnThread and ExitMoviesOnThread. Listing 6 
shows the basic skeleton of a method that is to support 
QuickTime calls on a background thread. 

Listing 6: Exporting a movie in the 
background (skeleton version) 

' tlEAction)doExportOnThread Hid)sendsr 
( 

NSAutoreleasePool* pool = [ [NSAutornlefiUFFool a 1 loci 

initjj 

OSKrr err * EnterHovieiiOnThrefid [0): 
if (err) 
goto bail; 

err = AttacMovieToCurrentThreadi ftnovie qulckTijneMovle]): 

If (err) 
goto bail; 

// QuickTime/QTKii calls cjin go in here.,.. 

DetachMovieFromCurrentThread([movie quickTlmeMovieJ); 
ExitMoviesOnThreadC): 

baii: 

[pool release]; 
fNSThread exit]r 

] 

The EnterMoviesOnThread function is declared like 

this: 

OSErr EnterMoviesOnThread (UInt32 inFIags): 

Currently only one bit in the inFlags pamnieter is defined, 
namely kQTEnterMoviesRagDontSetComponentsThreadMode, 
Setting tliis (lag forces no change to be made to the 
Component Manager threading mode. By default, 
EnterMoviesOnThread automatically sets the Conij>onent 
Manager threading mode to 

kCSAcceptThreadSafeComponentsOnlyMode, wliich indicates 
that only thmad-.siife components shall lie allowed. Since 
tills is the mode we desire, we’ll pass 0 when we caU 
EnterMoviesOnThread. 


'When we are llnished using QuickTime API calls on 
a particular background thread, we need to call 
ExitMoviesOnThread, which takes no parameters. Each call 
to EnterMoviesOnThread must be balanced by a call to 
ExitMoviesOnThread. 

The main thing we need lo do is add some code that 
exports die specified movie into the filename indicated by 
the sender paraineter. That code might look like this: 

NSDictionary “diet = [NSDictionary 
dictionaryWitkObjectsAndXeys: 

fNSMutnber tiumberWitblnt:!] . QTMovie Ex port, 

[NSNumber numbertf i tbTnt: kQTFi leTypeSGPP), 

QTHovieExportType. nil]; 
tmavie writeToFile;sender withAttributes:diet]; 

Once The writeToFiletwithAtthbutes: method completes, 
we need to make sure that the progress panel is removed 
and that the movie is transferred l)ack to the main thread. 
We can do that by adding one more line of code, just 
l>efore the baii label: 

(self performSelectorUnMalnThread: 

^selector(finishedExportiii&) withObjectmil 
waitUntiiDone;YES]; 

Listing 7 shows our implementation of the 
finishedExporting method. 

Listing 7: Cleaning up after an export 
operation 

- (void) finlsbedExpt>rting 

[NSApp endSheet: progressPanel] ; 
tprDg,re$£Fan&l cloae] : 

AttachHovieToCuirrentThread ([movie quickTimeMovie]): 

I 

And so we are done building the doExportOnThread: 
method and the methods it calls. 

Handling the Cancel Button 

One final task awaits us, namely displaying the 
progress sheet, Li(>dating its progress bar, and handling 
clicks on the Cancel button. It turns out that we already 
have mo.st of the code we need at hand, in the form of our 
movie :shouldContinueOperat*on:wiIhPhase:atPercent:withAttri 
bates: delegate method. 'I 'he first thing we need to cliange 
is the cheesy way in which we detect clicks on the Cancel 
button. In the nib file, we configure that button to initiate 
tlie doCancel: action, implemented in Listing 8. 

listing 8: Handling clicks on the Cancel 
button 

- fIBAction)drsCanreli (id)sender 

1 

cancel ** YES; 

1 
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ert - noEtrj 


Then, in the delegate methtKl, we Uyas all tlie ctxle 
that lcx>ks for niouse-up events in the 1:>utton and replace 
it with this easy lest: 

if (cancel) 

err “ uscrCanceledErr: 

Alst)^ we cannot set the values of the text held and tlic 
progress bar from within the delegate methcKi, l>eaiusc 
this delegate method wraps a movie progress function, 
which is ciilled on the sante thread as the export 
operation — that is, on a background thread. In general, 
a background thread must never directly alter the 
application’s user interface. What we need to do is have 
tlie delegate method use the NSObject method 
performSelectorOnMainThread:withObject:waitUntilDone:, as 
we ditl earlier So well rework the various case blocks 
like this: 

case QTHnvinOperstionOpdatePercentPhase: 

// updalr the pcarni done 

[self updatePro^reai^Top toNumher:percent! ^ 
break: 

Listing 9 shows our definition of 
updateProgress:toNumberL 

Listing 9: Sending IJI updates to the main 
thread 

' (void)updatePrQgreas:[KSString*Jmsg 

toNuraber: (NSWumber*) vaUie 

( 

NSDirticitiary* diet “ [NSDictlonary 

dlctionaryWithObjectsAndKeys: msg, , 

value, value", nil]; 

Iself perforniSelectorOiiMainThrefld: 

fiselec 10 r (updatoProgrenElivMa i nThread ■) 
wlthObjeclidlet waitWntiiDonpiHO]; 
return : 

* 

Finally, Listing 10 shows the code we run on the main 
thread to update the items in the progress panel. 


I 

OSErr 
switch (phase) ( 

case Ql'MuvieOperat ionEeglnPhase; 

// set up the progress panel 
[eelf updateProgt 0 Ss:up toNusiber: 

[NSMuntber numbe rWi t : Dl ] ; 

break: 

case QTMovieOperatlonUpdatePercentPhase; 

// update the. percent done 

(self updatcProgressiop toNimibar:percentJ: 

break: 

case QTMovieOperationEhtlPhase: 
break: 

I 

if (cancel) 

err - uscrCanceledErr: 
return (err = noEtr): 

1 


Conclusion 

In this article, weVe taken a ltx>k at executing QTKit 
methtKis on seconcLiry threads, in an effort to olTload 
lengthy openitions from llie main thread and thus improve 
the res(xmsiveness of our application. In paitioilar, weVe 
seen how to export a large movie without blocking the 
playback of other movies that we might have open and 
wilhoul preventing the user from opening other movies. 
Tlie basic rules we need to adhere to are relatively simple: 
(1) make sure to properly initialiy.e and deinitiaii2e the 
QuickTime enviromnenl on secondary threads (by calling 
EnterMoviesOnThread and ExitMoviesOnThread); (2) make 
sure to detach a movie from one tlircad and attach it to 
another Lhrc‘ad if you need to oi>erate on it in multiple 
threads (by calling DetachMovieFromCurrenfThread and 
AttachMovieToCurrentThread); and (3) make sure to 
perform any user interface processing on the main thread. 
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Listing 10: Updating the progress panel 

' EvoidlupdateProgressItlMainThtead: (NSDictionary" )dici 

I 

NSSLrlng* rasg ” (diet objectForKey: 

double value = [[diet obJfic!tForKey:@*’value’*] doubieValueJ 

* 100 . 0 : 

[progreesText setStrlrigValue:msBJ: 

IprogressBar setDoubltValue:value]: 


A few of tile routines used here are based on exxie by 
Micliael B. Joiinson. A more cxliaustive discussion of 
rlire:iding in QuickTime can Ix^ found in Techntad Note 
TN2 i25, '*Tliicad-safe pn>gramining in QuickTime", available 
at http//developer.applexom/technotesAn/tn2125.html. You 
can also find a discussion of tlie Quicklime tlircading APIs 
in tlie QuickTime 6,4 Al^l Refetence. 


For completeness, let’s Uike a last lcK>k at the revised 
version of the delegate method we are using to drive the 
progress updating (Listing 11), 

Listing 11: Displaying a cancelable 
progress sheet (revised) 

(BOOL)iiiovle: (QTKovie *)iBUVle 

fjhouldCont iriueOperatlun: (NSStrlng *) op 
wl ihPhaiie: (QTHov I eOpt^rat 1 on Phase) phase 
atPeccent:(KSMumher *)percent 
withAttrlbutes: (NSaictlouary buter. 


YitI 
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■ac OS I PragraBBlai 




By David Hill 


Welcome! 

While most of you liavc probably htraril of Mac OS X's 
2D drawing AFl^ Quartz 2D, how many of you liavu taken 
the time lu puil up the lieaders and get your iiand.s ditty 
figuring out wlial il can do? For those* eif yoti that haven'T, 
whether yoiiVe Ixjen tw bufiy or just kk) iniimidati*d to 
learn another drawing Al^I, I'm going to walk you througfi 
some of the Irasies in this article, fm not going to dwell on 
tlieory or the details of the drawing nuKlel. Insteati, we’re 
just gening To play with the AFI and perhaps learn stnnetliing 
along the way. I’ll present short snippets of dniwing code 
tfuit you c'an drop intc3 a sample pnjjecl and try out. Keel 
free to play with the ccxie and experiment on your own. 

rin Irasing the code on Mac OS X 10,3 (Panther) and 
Xctxle L5 so if youir running a dilTerent version of ihe OS 
or Xt^txle, yoifll need to adjust the content accordingly. In 
particular, walcli out lor Functions that are only availalile in 
Pantlier, The Quart/. 2D headers very specifically mark 
those APIs that are only available in 10,3 and later wiili tlie 
Hag AVAILABLE_MAC_OS^X_VERSIONJ 0^3_AND_LATER. 
In addition, while I’m providing a C<K:t>a project with this 
article, the Quartz 2D ccxie is clearly marked and valid for 
Carlxjn xs well as Coc’oa. Girbon developers should watch 
out for differences between the ccxjrdinate systems, 
however, since Cocoa and Quartz 2D f?lace die origin in the 
IxXtoni left c'orner with +y pointing up while Gitixin (older 
QuickDraw ccxie xs well as Girbon Events) assumes that 
the origin is in tlie upper left comer with +y pointing down. 

One tlnal note alx)ur Quartz 20: die headers, functions, 
and tytx‘s are all prefixed with CG as an abbreviation for 
Quartz 2D's older name, Core Gniphic:s. Liit^kily, Xccxle 
knows how to find the he-aden> when you necxl to lake a 


look, just hit CMD-D, type the name of tlie hc^ader youVe 
kK>king for (^'CGContext.h’', for example), and hit return. You 
can also CMD-doiible-click on a Quartz 2D type or function 
name in your ccxie and Xccxle will llnd the header for you. 

The Quartz2DShell Project 

■fhexse of you Ibllowtng along at home will need a simple 
pniject to hold the Quartz. 2D code sni(>pet.s we'll talking 
aliout. Either download the .siimple code for this article or 
start up Xcode and create a new Qxxxi appiiealion pmject 
(for simplicity, I'm not using the CJocoa Dexument-based 
tiroject). I’ve called mine Quartz2DShell but feel free to be 
moie creative. (Jnce Xccxle hxs created the projec.!, double 
t:lick on the Afe^inMcnnuiib to c:>pen it in Interface Builder. 
Switch over to ihe Classes lal) in ihe AtamAfetm.mb window, 
,searcli for NSView, dick on NS View in tiie dxss li,sL and select 
Subclass NSView from the Classes menu. IB should select 
tlie new NSView sulxlass (give it a ,suitalile name liice 
Quartz2DView3. Tlien, select Create Rles from ilie Classes 
menu and you're almixst done. Add a Custom View to tJie 
window, resize it to till the window, and set die resizing 
springs so dial die view tracks die window. Finally, set the 
view's custom claas to Quartz2DView and you're done. Save 
the nil) file and return to Xcode. You should see 
Qimrtz2DVieuih and Qiuirtz2DViffU[m wailing For you. 

Getting Started 

'llie first thing you need in order to draw willi Quartz 
2D is a CGConlextRef. For those of you familiar with other 
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drawing APIs, you can think of a CGContextRef as a 
QuickDraw port or a GOT device context. CGContextRefs 
hold your drawing sUile and give you a place to draw. 
Tlierc arc several different ways to obtain a CGContextRef 
hut for our purposes we’ll simply retrieve t>ne from our 
custom view by replacing the existing drawRect: method 
with the code shown l>elow. 

- (void)drawRect; (NSRect)r6ct 
( 

// gpi the current CGContextRef fi>r the view 
CGContextRef eurretit Cent ext “ 

(CGConiexLRef)[[NSGraphicBContext currentContext] 
grapblcisPort] ; 

// gnib some useful view size numhers 
NSRect houndi « Uelf bounds ]i 
float width KSWidth( bounds ): 
float hoighi: * NS Height ( bornids ): 
float originX = NSHinX< bounds ); 
float orlginY “ NSHinYt bounds ); 
float naxX ” NSNaxX( bounds ); 
float maxY NSNaxY( b-ounds ) ; 
float laiddleX - NSHldXC bounds 
float middleY =■ NSMidY( bounds ): 


LeCs Start widi some really basic drawing. Most of tlie 
Quartz 2D API is based on the conrepi of a path (we’ll 
talk alTout paths in just a niinute) but Uiere is a really 
straightforward convenience function for drawing 
rectangles called C G Context Fill Reel () CGContex!RtlRect() 
takes the CGContextRef you’re drawing into and the 
rectangle you’d like Quartz 2I> to fill laser! the following 
code into the drawRect: method and then build and run 
the app. 


// try 1 simple rectangle with the conventence fiineiioji 


CGConiextFiliRcct 

CGRect tectRerr “ 

GGReciHykt 2 ( DrigltiX + width / 4 »C), 


//left 
// Ixulom 


originY + beight / 4 . 0 , 
width / 2 . 0 * 


// wid th 


height / 2*0 )i 


// height 

CGContextFlllR^l ( currcntContfjxt * 


tnntR&ct 


); 


//// 

//// insert the Quartz 2D drawing cc>dc snippets tiere 
//// 

CGCoutextFlusJhl curreTitConioxt ); 

1 


Carlxjn developers working with WindowRefs will 
need to get the port for the window and then call 
QDBeginCGContextO to obtain the appropriate 
CGContextRef. Note that you’ll also need to call 
CGContextFlushO and then QDEndCGContext() once you’re 
done drawing. Your function drawing code should look 
sometlaing like this: 

CGrafFtr portPtr - GetWindowPort( wiudovRef ): 

CGContextRef currentContext “ NULL: 

QDBeginCGContext[ portPtr, &currentContext ): 

// insert tlic Quartz 2D drawing code snippetii hca* 

CGContextFlush! currentContext ): 

// update ilic window 

QDEndCGContextf portPtr, ^currentContext ): 


Rectangles 

As 1 mentioned earlier, the coordinate system of I he 
CGContextRef has the origin in the bottom left corner and 
the +y axis points up* Whal I didn’t tell you was chat the 
context is also set up such that one context unit is 
equivalent to one view pixel. As we’ll see a little later. 
Quartz 2D has a very flexible ccxirdinate transfomiation 
system based on the concept of the Current 
Tiansformation Matrix (CFEVI) and so you can cdiange that 
one-to-one mapping if you like. For now, well leave well 
enougli aU>nc and keep things simple. A.s long as we don’t 
change the Cl'M, we can use coordinates that match the 
dimensions of the view and gel the results we’d expect. 


You should see a large black rectangle in the middle 
of your window (Figt-ire 1). Since we’re basing our 
rectangle on tlic dimensions of the custom view, if you set 
up the resizing springs correctly in lb you shouki be able 
to resize the window and have the rectangle adjust 
at:cx)rdingly in real time. 



Figure 1: Black rectangles go with everything 


Now that yoLiVe drawn your first Quartz 2D graphic, 
leFs move on to a slightly more complicated topic. As I 
mentioned iiefore, Quartz 2D likes to deal in paths. In 
fact, the CGContexlFillRectO function really just creates, 
fills, and desuoys a rectangular path under the hood. Let’.s 
take a look at what tlie CGContexlFillRectO function is 
doing for us* Drop this code into die drawRect: ccxle in 
place of I he previous snippet: 

CGContcxtbeglnPatht currentContext ): 

CCCon t e X t Ho V oToFoInt( c « r r ant Cent ext, 

origin! + width / 4 * 0 . originY P height / 4,0 ): 

CGContextAddLineTaPuint ( eurr&ni.Context. 
origin! + width / 4.0 + width / 2 * 0 . 
orlglnY + height / 4*0 ): 


M/om 
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CGContfixtAdriLlneToPo i tit ( c u r retitCcjntex i. 
originX + widtli f 6,0 + wldtli / 2.0, 
originV + height / 4,0 + height / Z.O 
CGCon LexlAddLineTuPolnt( currenteantext, 
originX + width / 4.0, 
origin^ height / 4,0 + height / 2,0 ); 
CGContextFlliPathC currentContext ]: 


WWW 


Window 



Here, we're starting a new path with 
CGContextBeginPathO, moving to the bottom left corner 
of the rectniigle, adding lines along the bottom, right, 
and top edges, and then filling the path with 
CGContextFil[Path(). Note that we didn't have to add the 
fouith line to close the path ourselves. For the purposes 
of filling the path, Quartz 2D will automatically close 
the current path (if it is still open) with a straight line 
back to its starting point whenever we call one of the 
drawing Functions. 

One interesting thing to nt>te al>t>ut Quartz 2D and 
paths: drawing with the current path (either filling, 
stroking, or both) consumes that path. If we were to 
add another drawing call like CGContextStrokePath() 
after our call to CGContextFj|IPath(), nothing would 
happen. We would have to recreate our rectangular 
path in tjrder to draw- it again. Thankfully* since 
performing both a fill and a ,sirokc (drawing ihe 
outline) of a path is so common, Quartz 2D provides a 
way to dc5 both in one function call. Simply call 
CGConlextDrawPathO and pass in kCGPathFil(Stroke or 
kCGPathEOFil [Stroke for the drawing mode parameter 
and Quartz 20 will fill and stroke the path in one 
operation. 

In order for the stroke to be visilde t>vcr ilie filf Fll 
need to show you one more thing: colors, There are 
two imporiani colors in Quartz 2D: the fill color and 
the stroke color. There are several ways to set colors 
but, for the purposes of this article, we'll stick with the 
simplest iwo: CGContextSetRGBFillColor() and 
CGContextSetRG8StrokeColor(). (If you w'ant to 
investigate Quartz 2D's color .support in more detail, 
check out CGColorRefs and CGColorSpaceRefs). 
Replace the call to CGContextFiHPath{) with these line.s 
and watch what happens; 

// Set the red, green, bliie,:*iKl ;dpha color vsilue.': 

CGConiextSetBGBFillCoior( currentContext, 

1,0, 0,0, 0,0* 1*0 

CGContextSetROBStrokeCoicr( currentContext. 

0 , 0 . 1 , 0 * 0 , 0 , 1,0 ); 

CGCcuitextDrawPath( currentContext, kCGPathFiliStroke 

Now your erode should draw a red rectangle wltli a 
green ouitine. For those of you like me with poor 
eyesight* a bad monitor, or Ixjth, you tnay have some 
trouble seeing the single-pixel outline. Let's make the 
sin)ke wider and more obvious. Add this line before the 
call to CGContextDrawPath(): 

CGContextSetLineWidth ( ciirrentContext, 10 ) ; 


Figure 2; Looks like we forgot something 

Ah, now that the outline is more visible (Figure 2), 
you can clearly see why [ said that Quartz 2D would 
cloxse the path for the purposes of fHMng the path. 
Quartz 2D didn't automatically close the path for the 
stroke so the left edge of the rectangle doesn't have a 
green line. Close the path manually (Figure 3) by adding 
ihis call to CGContextClosePathO after the third 
CGContextAddLineToPointO call: 

CGContextClojiePatTi £ ctirrenlContext 



Figure 3: That's much better 


Lines 

Now that you've got a handle on recLangics, we'll 
move on to some of the fun thing,s you can do with lines. 
WeVe already added lines to paths to make our rectangles 
and changed the line width hui there are some other 
things we can tweak to control the way lines look. 
Replatre your rectangle code with the line code below that 
explores the different line cap styles. 
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// draw some wide lines with difrereni endcaps and dashes 

CGConteKtSetiloeWidthC currentContext, 15 ); 

CGContextSetLineCapC currentContext, kCGLincCapByrt }; 

CGConiexrBaginPathC currentContext ): 

CCCQtitextMuvcToPoint( currentContext* 
orlglnX + 15, orlginY + 15 ): 

CGContextAddLineToPoint ( curretitCoTitext, 
maxX ’ 15, originY + 15 ): 

CGContextStrok€Path( curreiilGontext h 

CGContextSetLlneCapC eurrentCootext, kCCLineCapRouhd )i 

CGContextBeginPathl cucrentContext ): 

CGContextHcjveToPolnt { cur rent Con text. 
originX 15, ortginY + 45 ): 

CGContextAddLiDeToPolnt ( ciirrentContext, 
maxX - 15, origiiiY + 45 ) i 

CGContextStrokePathC curreotContexL ); 

CGContextSetLineCape currentContext» kCCLineGapSquare ); 

CGCoiilextBeginPath( cur rent Cent ext j: 

CGContextMoveToPoint( eiirrentCotitext, 
originX + 15. origlnY + 75 ); 

CGContextAddLineToPoinIC cur rentContext, 
tnaxX ' 15, origlnY + /5 I; 

GGContextStrokeFath( currentContexL ); 


0 0 0 Window 



Figure 4; Line cap styles 


Tills code produces three fat lines (Fixture 4) with 
different end styles: butt, round, and square. Feel free to 
incre^i.se the line size or zcxim in (using Mac OS X’s 
accx.\s,sibility controls) to get a better look at tlie end caps. 
Also, notice that while the line with the kCGLineCapButt 
style ends right wlicrc the patli starts and ends, the other 
two tine cap styles cause the line to overflow the end fxiints. 
Tills happens liecxiuse the round and .sejuare cap styles diaw 
a hidfcircle and a .scjuare, resjiectively, centered on the end 
point of ilic path wliereas the butt cap style s<|uarc‘s off tlie 
end of the path perpendicular to the fiatli at the endpoint. 

0 0 © Wndow 
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Quartz 2D can also join lines in three different ways: 
miter, round, and bevel The following code draws three 
paths composed of twt) lines each (I'igure S). Notice the 
difference in the corners where the lines meet. Dcf>ending 
on the size of your window, the miter and lx,'vel join styles 
may look the same. Narrow the window slowly and the 
mitered lines will eventually change as the angle Ixjtween 
the lines increases (Figure 6). i don't know alxiul you but 
Fin really glad Quartz 2D ngures all of this out for me. 

@00 Window 



Figure 6: The miter foin looks different now 


// tcM the tliffertnt line join styles 

CGContextSetLineWidthC currentContext, 15 ): 

CGC ont ext S etllneCap( c urr e u t Co nt ex t, k CGLine Ca pButt ): 

CGCatitextSetllneJoin { cutrentContext, kCGUtueJO'ifiMiter )■; 

CGContext&eglnPath{ currentContext ): 

CGCoritextHoveToPoint ( current Context, 
orlgliiX + 15. originY i 105 ); 

CGContextAddLlneToPoi tit ( cur rent Context, 
maxX - 75. originY + 105 )i 

CGContextAddLincToPoint( curtentContext, 
originX + 15. origitiY + 155 J: 

CGContextStrokePatht currentContext ): 

CGConiextSetLineJoin( curceutContext, kCOLineJgitiRourtd ); 

CGCont extaeglnParh( cur rentCentext ): 

CGContextHoveToFolru ( currentContext, 
originX + 15. origlnY + 175 ): 

CGContextAddLineToFoint ( currerrL Context. 
maxX - 75, originY + 1/5 ): 

CGContextAddlineToPointt currentContexL * 
originX 4 15. originY + 225 ): 

CGContcxtStrokePath( currentContext ): 

CGContextSetLineJoin( currnntContext. kCGLineJoinBevel J: 

CGContextBeginPatbC currentCnntext )i 

CGCont extMoveTo Point ( current Cnn t. ext, 
originX t 15. originY + 245 ); 

CGContextAddLineToFoint( current Con text, 
tnaxX ■ 75. originY + 245 ): 

CGCofitentAddLineToPointl currentContext. 
origin^ + 15, originY t 295 

CCContextStrokePath( currentContext ); 


Figure 5: Line join styles 
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Paths 


Up to thi» wcVc Ix^en drawing by settiiig up the 

airrent pjith In a context and then asking ttie context to 
draw tltal path. This works fine but it can lie awkward when 
you want to reuse a path multiple times. Luckily, Quartz 2D 
includes a separate path object, CGPathRef, that you can 
create and rease over and over again. Tlie usage patiem is 
simple: create a mulaljle path, add to tlie patli in much tlie 
same way as we did for die current path in die: context, add 
the jrath to the exMitext, imd ask die context to draw. Note: 
the NULL (laramcters Ixtiow are CGAffineTransforms t\n\t 
allow you to transform die fioints as they’re added tti the 
path. We won’t worry alxiut those in diLs aiticle so we’ll pass 
in NULL to keep Quartz 2D from doing any extra wtjrk. 
Drop in the code snipjxri lx::k)w and try ii out. 

// ciratc i p:iih untl ikc it 

path “ CCPathCreateHutableU; 

CCPathMoveToPointf path. Mti, 
originX + 15. origiaY + 120 ): 

CGPath/ydLin<^TDPoltitt p^th. KtILL. 

maxX ' 75, orJglnY + 120 ); 

CGPatMd(3Liai?ToPglnt( path. HULL. 

orlglaX + 15. originY + 170 J: 

CGContextAddFathC currentGoutext. path ): 

CGPathRelease( path ): 

CGContextStrokePath( currenrContext ); 

Not too exciting, is Have patience. We're getting to 
the g(H)d part. Creating a CGPathRet, adding to it, drawing 
with it, and then releasing it isn't terribly efficient. What 
you really want to do is create the path, set it up, and then 
use it multiple time.s before releasing it. Get rid of the 
boring path code aliove and replace it with this: 

GGConiexiSeiLlueWidtht curreiitCgiitext. 2 ): 

// crraie ;uid set up the path ,staning at the origin 

pnth " GCPathCreateHutabieO : 

CCPathMoveToPolnt( path. HULL, origioX, tiriglnY j; 

CCPathAddLineToPoint( path. NULL, 
originX + width / 8,0, ortginY )t 

CGPath«oveToPoint( path. MULL. 

originX + width / 8.0. originY 0.25 * width / 8.0 }: 

CGPatbAddianeToPoinlt path. NULL. 
originX + 0.75 ' width / 8.0. 
originY 0.2b * width / B.O ); 

// iratislair tlu* origin Ur thf middle of the window 

CGContextTranslateCTH{ currentCont^xt, 
middlaX, middleY ); 

// sode rht context so tliat tilings arc twice as i)lg tn Ixitli iUtt-ctions 

CGConte3EtScaleCTM( currentContext. 2, 2 J; 

float radlanuToRptate '' 2 ' M_Pi / 21: 

int i: 

for ( i = D: i < 21r J 

I 

// ackl (lie path to the context and draw 
CGContextAddPath( currantContext. path ); 
CGConte35tStrokePath( currentContext ); 

// iotatc the etmtext just a bit 

CGContextRotateCTHf curreutContext, radiansToRotate ); 


// we'R' done with the path 
CCPathReleaee( path ); 



This code adds some new twists {Figure 7) to what 
you’ve seen before by itianipuhuing tlie CTM, Remember 
the CTM? T told you that as long as we didn't mess with it. 
we could draw using view c’(K)rdinates and things would 
turn out like we'd exj^ect. Well, now^ weVe got to change 
the CTM or we won't be able to see that weTe drawing 
the CGPathRef object multiple times. In this case, we set 
up the path, sec up the CTM so that ihe ccxirdinaie system 
origin is in the middle of the window, make tilings a bit 
bigger, and then enter a loop, 'llie kx>p draws the path 
object and then rotates the CTM a bii so that we don't 
draw the path over itself 21 times in a row. Note: 
CGContextRotateCTMO rotates the CTM such that the next 
path you draw appears to rotate counter-clockwise 
around the origin. 

There'.s one la.st stop on our tour of paths and lines: 
dashe.s. Quartz 20 makes it almost too simple to draw 
lieautiful dashed lines. All you need to do is set up an 
array containing the dash lengths you want, make a call 
to CGContextSetLineDashO, and stroke your paths. Quartz 
2D takes care of the rest. Take this oxJe for a spin (Figure 
8) and see what yr)u think. 

// play with lint dashes 

CGGfintexrSeTLIneWidthC eurren 1.Context, 10.0 ): 

float dashPhaae = 0.0: 

float dashLeEgthsU = I 20. 30, 40. 30. 20. 10 I: 

CGContextSetLiTieDasht currentContext. 
dashPha^e. dashLengths, 

aizegfC dashLengthB 5 / filxenft float ) ); 

CGContaxtMoveToPol Eit ( current Context, 
originX + 10 , jnictdleY }; 

CGCon tex tAddLlneToPoitit { currentContaxt, 
muxX - lU. middleY ): 

CGContextStrokePathf cutrentCotitext }: 
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the dashLengthp antiy seta up dashes of length of 
20, 40, and 20 witli gaps in iDetween of length 30, 30, and 10. 
Yt>u ean also adjust tlie pliase (wliere die dash frattem starts 
“ play with it a bit) when you call CGContextSetLineDash(). 

Dashes work fine with straight, horizontal lines boL 
that's lK)nng. Let's try something more interesUng. Here's 
another snippet that draws tatrves instead of lines (Figure 
9), Add this crxle after Uie CGConte)ctStrokePath(): 

// play curves & dashes 

CCCotilexlSctRGBFillColor( currentContext, 

l.Op OpOp 0.0. 1.0 ]; 

CGCqntextSe tRGBS i rokeCola r( currentCantext. 

OpOp 1,0. O.Op 1-0 ]; 

CGContextHoveToPoint( currentContexl, roiddleX, maxY ): 

CGContoxtAddCurveToPoiutt currentContext. orlginX- maxY. 

orlglnX, 0.667 " maxY, HiiddieX. middleY ); 

CGCcj N text Add CurveToPoint( cur rent Context. 

maxX. 0.1^3 * moxY* tnaxX, originY, middleX. erigiriY 

CGContextAddCurveToP»int( currentContext. origiuX. 

OriginY, originX, 0.353 * maxY. middleXt iniddleY ): 

CGContextAddCurveToPointt currentContext. maxX. 

0.667 * oiaxY, maxX. maxY, middleX. maxY )i 

CGCunLextDrawPath( currentContext. JtCCPatiii'illSiroke ); 



Figure 9: Dashed and filled figure eight 

Notit:e how tlie dash pattern moves along the curve as 
you resize the window while the pattern remains fixed on 
tile horizontil line? That is tiec-ause Quartz 2D starts the dash 
pattern ai the Ix^ginning of the path and repeats the paUem 
as many times as necessary to rejich the end of tlie path. If 
tlie iengUi of the path changes, Quartz 2D just continues the 
pattern as necessary, Since we’re always Irxiking at the 
lx:ginning of the path for the .straight line, the fraUem doesn't 
appear to shift* However, witjj tlie curve we can see a clear 
beginning and end of tlic path, lliat makes the atidilional 
diislics added and removed quite obvious as the curve 
length changes. 

Shadows 

Mac OS X has always provided very nice shaclow.s 
under windows and other Ul elements. With Panther, 


Apple added APIs to Quartz 2D to allow you to draw your 
own shadows, lliere are two shadejw^ APIs: the simple one 
and the slightly less simple one. The former, 
CGContextSetShadowO, sets up a simple black shadow. 
The latter, CGContextSetShadowWithColor{), allows you to 
specify the color f>f the shadow* Well use the black 
version Iictc but kntxk yoitrself out with colored shadows 
if dial's your thing. Add this tine right after Uie ‘"play with 
curves ik dashes” comment* 

CGContextSetShadow C curr^ti tCont ex l. 

CGSizeMakeC 14,0. -14.0 ), 7.0 



Figure 10: New and improved with Shadows! 


Now our tiirve has a nic’c soft sliadow (Figure 10) but if 
you kx>k closely you1l see tiiat the dashed green outline Is 
casting a shadow on tlie red filled pc^itk>n. IV^x^nding on the 
look yr)u’re going for, ihai may t>r may not lie what you want. 
It turns out tliaL even tliough we’re making a single t ail to fill 
and stroke Uie path. Quartz 2D Ls perfoi-ming two sejiarate 
operations ;md each result has a sliadow* Tlie fill comes first 
with the bottom sliadow itnd then the stroke comes along and 
draws its shadow*^ on top of the fill* So, if you want tile 
wmi lined result of the two opcralioas to liave a single 
.shxsdow, what do you do? You'll need to use a tniasparency 
layer, yet anotlier new featuiie added to Qmirrz 2D For Pantlier- 
Transparency layers only reepire two function calls, one 
to l>egin the layer and one to end tlie layer* In lx?tween, all 
Quart/, 2D drawing for tlie context goes into tlie layer 
iaslead of the destination of the ainlexl* Once you end the 
layer, alJ of the drawing in liic layer is composited into the 
c:ontexl using the shadow state of the contexL It will nuike 
more sense if you try it out yourself. There* are two lines of 
code below. Add the CGContextBeginTransparencyLayer() t.:all 
right after Lite call to CGContextSetRGBStrokeColor() and llic 
CGContextEndTransparencyLayerQ rail right after the 
CGContextDmwPalhO call, 

CGContextBeginTraiisparetieyI.ayer ( currentContext, MULL }: 

CGContextEndTranspareficyLaycrC currentContext ) : 
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Figure 11: Just one shadow this time 

With that change, you sliould .see your green-outlined, red- 
filled figure-eight with a single shadow Ixfitind the whole thing 
(Figure 11). Oh, and you're probKibly still drawing tlie black dashed 
line in the tackgraund, Tnuisparenty layers m^ike it very easy to 
add shadows to whole groups of objects. As their name implies, 
you can also use transparency layers to properly Iriindlc [ilplui 
compositing (traasparency) of multiple objects at the sante time by 
setting the alpha value for the context [before you lx!gin the 
iranspitremy layer Call CGContextSetAlphaO l^efore you call 
CGContextBeginTransparencyLayer() and the contents ol‘ the layer 
will lx: cx^niposited back into tlx context widi that alpha value 
when you end the layer. To see this in action, add the fi>liowing call 
right Ixfore yt>u Ixgin the layer: 

CGCantextSslAlpha( currentContext, 0*5 ): 

Ntjw the whole figure eight has faded out and you can see 
some of the black dashed line running through the middle 


(Figure 12). You can also see the faint outline of die figure’s 
shadow thniugh the red fill on the left side. 



Figure 12: Fading out 


Wrap Up 

t hope youVe enjoyed our brief exploration of Quartz 2D. 
Tliere's so much power and elegance in tlx API, you really nevd U) 
sit down and play witli it for a while lx*fi)re you get a feel for what 
it do. With any luck, IVe given you enough of a taste of Quarts 
2D that yoifre reiidy to gci f)ff and experiment on your own* Enjoy! 

_!jaj 
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Nuts About 


SquirrelMail 

W alking into MacWorld Expo at the Moscone Center in San 
Francisco with an Exhibitor’s badge the day before the 
Expo opens is one of the strangest experiences to be 
had. There’s the sound of duct tape whizzing off of rolls, and the 
slap of mats falling into place, accompanied by the hum of 
electrical equipment. It’s a great chance to walk around and get 
acclimated to the lay of the land before the crowds pile in. 


Away from the Office 

S<x)nLT or bier, though, the to check account home, withoiu either setting up m alieraite SMTP 

email hits, and llicn it [xx-xmies t|uite appjirent |X)rt or the ISP's own SM1P st^rver. Not ux> long ago, ;ill a home 

that even though the Ixxjtlis ate partially set brcxidbtind user had to do wils use autlicntiaited SMTP, but these 

up, there^s no open Airport networks days even that’s not a fait aecompll Ihe ISPs daiiii to Ix' bkxking 

availal:)le. and witliout a [xisswoid, no way to port 25 iit die name of sj)am prL'veniion (and they usually do ii 

check email, but then, towards die Ixick of uitfMmi notifying tfmr a4Stomersfirst), but ifs pretty envious that 

Moscone, there’s a few iMacGSs setup for an diey want to lock you into using their email servers and email 

“Internet cafe" and there's someone sitting atklresses, wliicii is die easiest miy they have of iasunng thiit you 

there feveiishly ty|:)iiig away. After testing won*t switch to another ISP with a Ixtier deal or faster service. My 

some of the other iMacs, it's obvious that the giiifnend, for example, switched to Covad DSL service over a yeair 

only one dial works is the t>ne he'sming, and ago, yet still [>ays $1195 a nionih for Yaluxi dial-up service, just so 

.sitting there politely isn’t going to licip, as if it she am "save" her email address. IPs a scam on a grand sc:ale—even 

were the last jxiblic phone on the planet if you’re savvy enough to register your domain name, and 

(which it Is, son of). Wliai makes it even purdiase email services or even run your own emii\ server, you 

worse Is tliat he's using StiuirrciMail, anti miglii not able to ea.si!y send mail via that account, 

judging by the numlxr of folders and In ihe.se days of predatory if your lircxidband provider 

subk)l<Jurs in the skle iTiir, ids olwious that he's decides to bkx-'k it. Where web browsing speeds might l>e 

an email nudxiU, and dial he’s never going to accelerating at a lireakncck [r4K:e, Ihji where sending email 

stop, since he's got Access to everything he's dirtmgh any server except for the ISP’s is heavily deprecated it's 

every received sent, and squirreled away webmail that's betoming an aiisolutely critical service for 

Every day I liL“ar more and more corporate email users when they'a^ out of the office. Aircr all, 

iastances of wliat I oill die "’great SMTP which ISP would dare to block TCP ix>rt 80, througli which all 

(Simple Mail Transfer Pnottxol) lockdown," i>a.sic World Wide Web traffic travels? Although high-end 

wiiere ISPs such as Earthlink, Comcast, IICN groupware servers like MicTOSoft Exchange and Ijotus Notes have 

and odiers are blocking ail irafBc over TCP f^tured webmail since the mid 1990s, oilier entities like G(x>gle 

port 25, which meaas that it’s )>ecome are gelling heavily into webmail services, taking advantage of 

increiLsingly difliculi to use a corponite email their well-known Imind names and their ISP-independent status 
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to lure etruiil users in park llieir eimil addresses ai the gimilcotii 
domain for Lite long term (witli wickedly fast srarclies and two 
gigabytes of storage), so that atrcttunl liolders may switch ISPs 
with impunity as they move from location to kxation or find 
lx*tter deals on broadlxtnd, while being exposed to more and 
metre of Google's pay-per-click ads, wliich liave now liecome 
both the ubiquitous marginalia and lip jars of web sites. 

So, where once web-based email was the itK>l that was 
occasionally used to send and receive cfnail while away from 
the office when a corporate laptop wasn’t available, it's now 
l>ecome a stantktrd arrow in the corporate quiver—often tite 
lifeline of communication tetween remote email users and the 
main office when standard email server is bkxkech or when a 
VPN is too unwiekiy or when corporate [T help desk staffers 
want to draw a line in the sand when it comes to supponing 
their employees' home networks. 

Highly Trained Squirrels 

Roald Dahl's Chatiie and Ihc Chocolate ivictofy featured a 
rtxxn hill of sptxially trained Squirrels that tested eat!h nut lliat went 
into Wonka candy liars, then tossed out ifie ixid nuts and shelled the 
good. In the same vein, it sexms tliat Apple's OS X Server 
Development team coveted trained squirrels a.s well! Tlie squirrels 
Pm speaking of are the h;ial-w'ork(ng rodenLs n( tlie SquirreLMail 
project, an o|xm-source PHP (Pre Hy^KTlext Prexessor) script living 
at httpy/squirrelmailsourceforge.net that leverages the Apache web 
server to provide a powerfeii and exteasible webiiiail service. 'Ilie 
S(]uiiTclMail team descrilies the project as: 


Sourcefi>rge.nfcH for a number of years, like Pink Floyd's “Dark 
Side of the Moon,’’ iPs always hanging nc^iir the top of the charts. 



SquirrelMail 


webfTiail 

for 

nuts 


Figure 1. Highly Trained Squirrels Sort Your Mail for You 


However, it seems that the OS X Server team wasn't 
exactly proud to employ the little varmint, so they tried their 
best to hide the sc)itirrcl beliind the scenes, a charade tliat’s 
easily foiled by a peek into the Terminal Cor just the OS X 
Server Web Services Documentation). Like many of the open- 
source projects included with OS X Server, there's an amount 
of obfuscation to cover up the origins of the goodies, at lea.st 
at the GUI layer, l^ut once logged into SquirrelMail, regardless 
of whether the logrPs an actual squirrel or postage .stamp, 
there's no mistaking tlie interface! 



Figure 2. "Squirrels? What Squirrels?" OS X Server 
Webmail Logo 


. * . a standards-based webmail package 
written in PHP4. It includes built-m pure PHP 
suppon for the IMAP and SM'IP prouKols, 
and all pages render in pure HTML 10 (with 
no JavaScript required) for maximum 
compatibility acrass browsers. It has very few 
retjuircmenis and is very easy to configure 
and install. SquirrelMail has ail the 
functionality you would want from an email 
client, including strong MIMF support, 
address books, and folder manipulation. 

From its inception. SquirrelMail was designed with the 
notion of ‘'install once, Access with any browser, on any 
pi a dorm” in mind, wiiiclt is a great conipliment to the basic 
premise of web-lrascd email, w'here what operating system and 
web browser the user Ls running, and on whai speed and type 
of network (and with what jxjrLs blocked) makes little or no 
difference. Install St|uirrelMail, configure it, and tlien let tite 
remote users do the rest themselves. It's a tiling of beauty. 
Given that Apache and PHi* come pre-installed on nearly all 
UNlXy operating systems, it's no surprise that Sc|UirrelMail has 
become die darling of the Linux, BSD. and OS X wodds, and 
quite simply, one of the most Lonsisiently popular prtijects at 


Getting Going (and Along) with OS X 
Server 

Enaliling SquinelMail on OS X Server is a trifle, simply edit 
the web site settings in Server Admin, and check the ‘‘wehmair 
box in the opiioas list. Email services must lx* running and 
configured, along with user accounts tliat have email boxers and 
IMAP (Internet Mail Access Protocol) enabled IMAP is a 
requirement for SquirrelMail (and all w'ebmail programs 
designed widi the sanity of the administrator in mind). Using 
IMAP means that all messages 

V* EdrtiiKH. 

—- 0|Mi»o»rt BeUrm Logyag AjIimm -- 

Enable optiofis: ^ FoEcter listing 
SWtbOAV 
C CCI Exteutian 

O Server Side IndvdeiS CSSt) 

Q Perfomunce Cache 


Figure 3. Checkbox to Enable WebMail in Server Admin for 
Tiger Server 
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remain on the server, and are read on the server, witli only the 
HTML representation of their content aaually transmitted back 
to the webmail users. If no attachments are involved, email 
displays via the web browser as quickly as the server can 
process the messages and generate the H'l'ML (dependent, of 
course, on the conneaion speed of tlie user logging in). Once 
enabled, all the user has to do is navigate to 
httpiZ/yourwebsitenameA/vebmail, and then login at the prompt: 



Mac (XS X Server VVebMaU Login 

Nan«: ~ 

Password: 

( L&girr"} 


Figure 4. Http://yoursite.com/webmail 

Although Sc|uirrelMail has l^een bundled with OS X Server 
starting with version 10.2, ii reitlly started to kick some furry tail 
with OS X Server 10.3 and 10.4, which use the Cyrus IMAP 
server, rather dian the Apple Mail Server Carltonizeil From 
AppleShare IP that OS X Server 10.1 and 10.2 featured. With 
Cyrus, SquirrelMaii absolutely Jlies, and with a decent 
broadband conned ion, nin l^e even faster than mtxst nothwei} 
mail clients, such as Mail.app or Microsoft Entourage. 

Hie Squirrel Behind the Curtain (a.k.a Road Kill) 

Nomially, Squira-IMail would be installed into a single 
direcrojy as a separate virtual domain on a web server, so that the 
users wtmkl go to http;//webmail.you rdomain.com, nuher than 
http://www.yourdomainxonrvWebmail. Apple's implemeniation, 
however, makes it ntuch easier to levenige a single copy of 
SquirrelMaii over multiple sites, Finding the "parts" of the 
SquirrelMaii installation isn't exactly stniightforward. For example, 
the URL would suggest dial SquirrelMaii was insiallc^l in a 
subfolder of the wehroot /Ubrary/WeliServer/Document.s, but it 
isn'tf It's akiiosi as if OS X Server flattened the ptjor PHP script, 
scattering its code to the far cornel's of the OS X Server 
file-system. One interesting featuR* of Tiger Server is that when 
webmail Ls enabled in the default web site, it’s now indicated via 
an “Available services:" Ixix under the 'figer Server Logo, which 
serves as a hyperlink to SquimelMail! 



Available services: 


Webmail 


* FOWfatDSY 

w Mac OS X Server 


Figure 5. Webmail link on Tiger Default Web Page 


Apple’s implementation of Squin-elMail starts in the 
/etc/httpd direciory with the rather self-expianatory 
hitpd_squirrelmail.cc>nf file: 

nagitest:/etc/httpd luostadminS cat 
bttpd_equirrelmaI1,conf 

# Config rile for linking SquirrelMaii tn MacOSX Server 
Web Server virtual host. 

Add the following line to each virtual host for which 
on want SquirrelMaii: 

Include /etc/hftpd/httpd_Equirreliiiall*conf 
Browsers will then be able to reference SquirrelMaii 
with a URL like 

if http: / /vlrtualhost .example.com/yebMal 1/ 

Alias /WebHail /usr/share/squirrelmai] 

Allas /webroall /usr/share/aquirrelma11 

<Directory /uEr/sharc/nqul rreliiia±l> 

Options Indexes FollowSymLinks 
</Directory> 

'Ihe caimb trail leads to /iisr/share/sqiiirrefmaii, where the bulk 
of what a “nomiaf" SquirrelMaii insialiaiion lives* 'Ihe first thing 
to do is replace the postage stamp logo with llic company, club, 
user group, or house t>f worship logo. To do so, simply prepare 
the logo in one of the supported formats C.png, .jpg. *gif), and 
copy it to the /usi/share/squin-elmail/iinages direcuiry. Next, it's 
time to fire up the StjiiirrelMail configure script: 

nagitest */usr/fihare/aquirreljiiail mostadttln$ sudo .^h 
configure 

SquirrelMaii Configuration ; Read: config.php (1.4.0) 


Main Menu “ 

1* Organization FeeferenceE 

2. Server Settitigs 

3. Folder Defaults 

4. General Options 

5. Themes 

6. Address Books 

7. Message of the Day (MOTD) 

8. Plugins 

9. Database 

10 . Languages 
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D. Set pre defined settings for specific IMAP servers 
C Turn color on 
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S Save data 
Q Quit 

Command » I 


contains mincH^ncoclcd files send with email messages: 
na&lte5t:/vat/db/eqtjlrrelaaH/attachments root# is al 


'Illis menu-driven cxinfiguration scTipt is lx)th 
simple and powerl'ul Ifs stanewhal reminiscx!nr of the j>ir-weh 
Internet, where a cousin of the Stjuirrel, known as Gopher, served 
up information via text-djiven menus. Changing the log^i on the 
webmail login page is as simple as cho<>sing "Organization 
Piefeaiices'’ from the menu and typing in (lie jrath to tlie new 
iimge: 

SquirrelMaii ConfigureLion : Read: config.php (1,4.0) 


1 WWW 
1 WWW 
1 WWW 


Organisation Preferences 

1. Organization Name 

2. Organization Logo 

1* Org, Logo Width/Height 

4. Organization Title 

5. Signout Page 

6. Top Frame 

7. Provider link 

http://WWW*equirrelmaii.org/ 

8. Provider name 


R Return to Hain Menu 

C Turn color on 

S Save data 

Q Quit 


Hac OS X Server WebHail 
mostlogo.gif 
( 0 / 0 ) 

SquirreiMaii $versiDn 
top 


SquirrelMa il 


Command >> 


# O # Mac 05 X Server WebMaU - Login 


O 0 & O hiLp://na3tieiLto<a1/iwebmai) 

SAck AfrloAd loubon 

M(!)5r 

Mar OS X Server WebXf aO LoRin 
Namc:l 

Password: ^ 


f Igg irt j 


Docununr Pqm 


Figure 6. Webmail login with custom logo 

To cover every single conflgumtion option in SquiiTelMail 
would take a very long time, hut it:s interesting to note tliat the 
Configure ,scripL kicks off a [>erl which lives in ihc 

/LLsr/sliare/squirrelimil/config directory called conf.t>l. Executing 
conf.pl (use sudo perl oonf*pl) from the coinimnd line brings up 
the familiar ScjuirrelMail configuration menu, but adds a little extra 
hint when exiting: 

Exiting conf.pl* 

You might want to teat your eonfiguration by browsing to 
http i //your squ!rrelmail’lQcation/src/configteat * php 
Happy SquirrelMaillog! 

While the configtest.plip feature is nice, it also can be 
somewhat of a security risk, since it reveals details alK>ut die 
server configuration, notably regarding die authentication 
settings of the IMAP server Anodier very important directory to 
administering SquirrelMait is /var/db/sqiiirreimail/ and iLs two 
subfolders, attachments and data* The attachments folder 


whael 2614916 Jul 26 23:5^ NUSgtli>dJi6qiMQr0eO6CE3KPlxISXgSJB 
wheel 7947926 Jul 27 00:05 XHAca4004T2xzloNZCzo5G3UznWAolYl 
wheel 4082991 Jul 26 23:53 bJEprLCFiVQKrY6a0u0ritllXxWp5hfDr 

ll might not hurl to chet:k diis directory and periodically clean 
oui the contenLs to *save some disk space. Ii may even lx: 
worthwhile to script a snxill cron or launchd job to pericxlically 
sweep away the ScjUirrelMail droppings* In a similar vein, if a 
particular user experiences anomalies in the dLsplay of iheir 
webmail, strange enor messages, or long delays wliile logging 
in, it might be worthwhile lo dean u[) an session file-s, or delete 
the users' ,pref files in the data folder, for the most pan, the oui- 
of-the-lxjx SquinelMail configuration for OS X Server is ]>retty 
good, but can be made a lot Ixattrr with just a few moie tweaks* 

Adjusting Authentication 

'Itie first thing to do Is U) review how the SquifielMaii web 
interface sends its authenticarion credentials to the imap server, atid 
wliile theie’s tediniGilly no risk Ixxraase the out-ofthe-box 
configuration has the IMAI’ server and the webmail server on the 
*same Ixix, die login credentials aren't .sent over die Internet 
However, I still prefer SSL security for wdxmil, diougli '^rolling your 
own” SSL cerrificaTes is a topic for anotlier column* It's mandatory if 
using S<|uirrelMail to access an IMAP aceexmt on a mmote server, 
whicli 1 do, liecause I like to urn my own Tersonat” copy of 
SquirrelMail on my own CS, and sometimes my cx>mfxiny provides 
webmail services for customers w'ho donT want or (un'i maintain 
dieir own webmail server for whatever reason* Also, disabling the 
login and plain autheniicidon tyjK^ for Mail Services in OS X Server 
10,4 ncquiRcs lliat ScjuimelMail also lx: configured for an allowcxl 
authentication type, in this case cram-md5, wliidi wliile not as 
secure as SSL, is certainly mudi lx:tter than plain and login 
aiuhenticuiion, still used by a surprising number of mail .sc‘rverx* 
First, the email service needs to lie configuntxi* Authentication types 
are located in Server Admin, Mail Service, Settings, Advanced: 
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Figure 7. Disabling Insecure IMAP Protocols 
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Ihe next step is to adjust tlie authentication type in 
S<[uirrelMairs configure script, and tliat's done in the IMAP 
server settings section tif the Server Settings menu. Simple. 

IMAP Settings 


4. 

IMAP Server 

: localhost 

5. 

iHAP Port 

: 143 

6. 

Authentication type 

: cratn-mdSi 

7. 

Secure IMAP (TLS) 

: false 

8. 

Server software 

; cyrus 


Increasing the Attachment Size 

Another oul-of-tiie-ix)x limitation is one imposed by tlie 
PHP library itself: SquirrelMail on OS X Server can only handle 
email attar:hments of only tuv meg£th)*tes or less. Wiiilc an 
Xserve running OS X Server 103 or 103 with a gig of RAM and 
an Xserve RAID attached by filx.T channel makes for a Jfying 
SquirrclMaiL the limit’s sinipiy the PHP default and with a few 
small cdiLs, can be macie to match to the attachment size limit of 
tlie Mail server itself. However, I have to point in all fairness out 
that the ttser experience of uploading a twenly-five megabyte 
attaduTient through a web browser might be somewhat differcmi 
than wliat end-users ex peel. As a matter of fa a, iVe found tliat 
some end usets don't adjust tlieir expectations when working at 
liome over a cable modem that might download at similar 
six^eds to what tlicy'rc used to at die office, but with much 
slower upload speeds. Even worse, i’vt: had cojiiplaints t^f 
S<|uiiTelMail “not working” simply Ijccausc' someone didn't 
understand how long it would take to ttpload a ten megabyte 
PowerPoint presentation via a diahup t'oonection. 



Figure 8. SquirrelMail default attachment size 

Uploading large files via a web browser t>n OS X doesn't 
really offer much in the way of a progress indicator, and if the 
connection’s slow (like dialup) or flaky (like dialup over a 


Bluetooth modem connection), then there's always the risk 
that the SquirrelMail user might be left m limbo. Bui if they’re 
forewarned, upping the attachment size can even make use of 
Cyrus’s ability to act as a file system, much like Folks would 
use a .mac account or a gmail account U> Sc|iiirrel away or 
transfer files. 

Tlie first suqirise is that the PHP distribution shipped with 
Tiger Server doesn’t include an active c<ipy of the PHP.ini file, 
the standard PHP configuration file. Luckily, tliere's an 
/etc/plip.ini.default file that can be copied and edited to spec. 
First, make a copy of the file: 

nagitest:/etc deaiiS sudo cp /etc/php.ifil *default 
/etc/php.ini 

then, open up the php.ini file in a favorite editor. Tliese days 
I'm partial to BBEdh's command line "bbediU tool, or 
Text Wrangler’s “edit’’ tool, hut pico or vi will also work just 
fine. IFs helpful to have something wit ft an easy search 
feature: 

dean$ sudo pico php.ini 

Now, find the first thing to adjust, die following line: 
«iaK_ex^cution_tiioe " 30 to iaax_e)tecut i on_t ime - 600 

this allows for longer uploads (ten minutes) wUiKJiit causing a 
limcoul. Next, adjust the line that read.s: 

»onrory_limit Bm to read ineiiiory_ limit = 32M 
Next is the line: 

p 06 t_inax_size “ ZH to pojBl_ max size " 7JiH 
Now the line: 

upload_max_filesi3€ ^ 2K to iipload_Tii/ix_f 11 24H 

Now, save the changes, ;md wlien l>ack al the command 
prompt, is.suc (he following command: 

naglrestr/etc dean$ sudo apachectl restart 

Restarting the Apadie web server forces the PHP library to 
(re)read its configuniiion file. At the l^iitom of the SquirrelMail 
page, the new max upload size is now rcflecied —24 megabytes. 
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Figure 9. Souped up nuts! SquirrelMaii stuffs its cheeks 
with attachments 


Necessary Adjest[sicjment, Fixing the 
Spellchecker 


Ry default, the Sc^uirrelSpcIl plugin of SquindMaO is 
disabled in OS X Server, i^ecause turning it on (easy to do in the 
plugias section of the configure script) reveals that the is pell 
librar>' it’s Icxiking for is nowhere to be found on OS X. And 
while there: might be a nice dictionary application and widget 
built into OS X 10.4, enabling die spellchecker in Mac OS X 
Server wehmail is the one of the most recjuestcd cnliancenients, 
second only to increased altaclunent sizes. 


# @ @ SquinrelSpetl is misconrigurtd. 


^ Sqiijrr£^p€U Is misii^otif^red. 


I tried to execute hspcll but it reiumcd: 

shi line It ispcll; command not found 


Ctose ^ 


rji'l 

Documtnc Don« 




Figure 10. Where the #%!@#!@# is ispell? 


manager, which 111 use for this example. In using either of the 
three methcKls, an installation of Xcode 2.0 is required if 
installing onto OS X Server 10.4. 

First, obtain and install either Xcode IS if using Panther 
Server, or Xcode 2,0 if using Tiger Server. Next, download a 
copy of the Darwin pt>rts binaiy installer from 
darwinports.opendarwin.org/downloads/DarwinForts- 
1,0,ding. Install the DarwinPorts .software. 

Next, navigate to /opi/kx:al/bin. and issue tlic following 
command: 

fia^itestj/opt/local/bin dean$ sudo ,/port install ispeli 

If all goc.s well, DarwinPons will download, configure, 
compile, and even clean up after the ispell installation, which 
will resulting in a compiled ispell at /opL/|(Kal/lnn/Lspell. Now 
all that's necessary is to fool the SquirrelSpell plugin into 
tliinking tlut ispell is in /shin, where it’s siippo.sed to be, and 
that’s easy enough to accomplish with a symlK^lic link: 

nagitest:/opt/Ifical/bin doan$ sudo In s 
/opt/local/bin/ispell /sbin/lspell 


Now, tlie SquinelS[x:ll plugin will be happy, and the 
s|x:llcbeck will work as advertised, making the end users .smile and 
chant with glee ‘^tliank you SquirrelMaii, thank you!" I3ut esf course, 
they’ll be thanking no one, not even tJieir system administrator, 
Ixx-ausc it shDuld liave worked, right outK>f4he-lx>x, everyone 
knows that all good email clients have spellcheckers, right? 


#00 


SquirrelSpell Results 


where ispellz qow7 


Found 3 errors 






Enor ded 


CTfaa^eKi: bed 


Change ChanoeiAft 


Suigesdons: bed ?] 
OocuRi an»s: 1 


AddtoPic 


. " Cciosc and Commii Close and CarteeTS 

, . V_-_. ..H-' 

|>DCument: 


_o^ 


Figure 11. Where's ispell? There's ispelf! 


The Sc:juirrcLS[>cll plugin expects to find ispell in /shin but it’s 
not included with the base install OS X Server webniail is .strictly 
BYOSC (bring your own spellchecker). There's Uiree ways to get 
a working copy of IsfX^il. One is to download the source eexie, 
patch it by editing one of the header tiles, and then install it. That, 
however, Is just a bit t<K> much work for sometliing this 
straigluforward. The oriier two methods are either to use the I'ink 
package manager http://Fink.sourc0forge,net, w^hkh I detailed in 
my February Source Hound Column, <h- the DanvinPorts package 


Take the Squirrel for a Walk 

So now that St|uirrclMail’s using secure authentication, can 
handle dccent-sized attacliments, and can catch tlie horrid 
spelling errors we all make while typing, i.s this die end for our 
beloved flying s<|uinel, or can we take it places it hasn't been 
before? Well, SquirrelSpell’s just the beginning. Visit 
SquirrelMaiLsoyrceforge,net and check out some of the myriad 
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of plugins, t: very thing from server-side plugins for spam filtering 
to out-of-office aulorespoTiders to LDAP integniiion plugins for 
the SquirreliMail address book are available to try, not to 
mention some fun stuff like appearance themes. SquirrelMail 
might be inherently simple, bin ii lias plugin ,supf>ort ihat no 
other webmail program Ciin touch. What else could be more 
uplifting and useful than a Squirrel that makes email tly away 
from the office, what would be its perfect companion? 



Figure 12. A Talking Moose, of Course: problem drinker 
is one who never buys" 

http://www.zathras.de/angelweb/moose.htm 

In Next Month’s Source Hound 

[ will return to the subject of my very first article for 
MacTech back in November of Iasi year—Apple’s Directory 


Services a.k.a ‘‘Open Directory” fll take a look at version HI 
and the new schema additions, features, and tools included 
with Tiger Server, as well as some open-source goodies like 
phpLDAPadmin and ask a Tiger Open Directory Master to 
say ''Ahhhhir and take a deep look inside...maybe for an OU 
or two? 

^^11 
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Relational 

database 


Object-oriented 

development 


A BEITER DfiTABASE CAN SPEED 
UPYOURDEVElOPMENrCVCIE 


If your relational database isn't a gcM>d march 
lor your object-oriented dcvclopmeiit, you need 
a new database. 

Cach^, the post-relational database from 
InterSystems, combines high-pcrforinance SQL 
for faster queries and an advanced object database 
for rapidly stt>ring and accessing objects. With 
Cache, no mapping is required between object 
and relational views of data. That means huge 
savings in both development and processing time. 
Applications built on Cache arc massively 
sealable and liglitmiig last. They require little or 
no database administration. 

More than just a database s^^stem, ( ^ache 
inc«)rporates a powerful Web application develop¬ 


ment environment that dramatically reduces the 
time to build and modily applications. 

Cache is so reliable, it’s the world’s leading 
database in healthcare — and it powers enterprise 
applications in financial services, government and 
many other sectors, Widi its high reliability, high 
performance and low maintenance. Cache delivers 
your vision of a better database. 

We arc InterSystems, a specialist in data man¬ 
agement tcchnolog)^ for over twenty-six years. 

We provide 24x7 support to four million users in 
88 countries. Cache is available for Windows, 
OpcnVMS, MAC OS X, linux, and major UNIX 
platforms - and it is deployed on systems ranging 
from mo to over 50,000 simultaneous users. 


InterSystems ^ 

CACHE 

Make Applications Faster 

Try a better database. For free. 

Download a free, frilly fLini.tioiial, non-ex pi ring eof>y of C^iclie or request it on CD at www.lnte rSystems.coin/match3 
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1 call protects it all 
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The new HASP family of products 
is the next generation in protection 
ensuring the highest level of security 
for your software. It provides an 
easy to use set of tools to protect 
once and deliver through a variety 
of licensing options. 
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ForWindows, Mac OS, Linux 


■ Data encjvption with industry standard hardware-based 
AE5128^bil 


■ Strang wrapper with code obfijscation prevents debugging 
and reverse engineering 


• API code generator for easy implementation and customization 


- Single arnl multi user license management 
' Secure licerise updates for keys in the ^eld 
■ innovative licensing models defined separately from pmtection 



Gef the FREE kit: Oeveloper*s Software, Guide and Demo Key at www,aiaddin.com/hasp Aladdin 
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